genericmappingtools / sphinx_gmt Goto Github PK

View Code? Open in Web Editor NEW

7.0 7.0 1.0 7.46 MB

Sphinx extensions for GMT

Home Page: https://www.generic-mapping-tools.org/sphinx_gmt

License: BSD 3-Clause "New" or "Revised" License

Makefile 4.59% Python 95.41%

gmt sphinx python earth-science geophysics

sphinx_gmt's Introduction

sphinx_gmt

Sphinx extensions for the Generic Mapping Tools

Documentation | Documentation (development version) | Source Code

About

This package provides a Sphinx extension for including GMT code and figures in your documentation. The extension defines the gmtplot directive that will execute the given code and insert the generated figure into the document (like the matplotlib plot directive).

Features

Supports any GMT versions
Works with both Bash and Python (PyGMT)
Include code inline or load from a script
Options to show/hide the code, insert captions, link to hidden code, etc.

Contacting Us

Most discussion happens on Github. Feel free to open an issue or comment on any open issue or pull request.

Contributing

Code of conduct

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

Contributing Guidelines

Please read our Contributing Guide to see how you can help and give feedback.

Imposter syndrome disclaimer

We want your help. No, really.

There may be a little voice inside your head that is telling you that you're not ready to be an open source contributor; that your skills aren't nearly good enough to contribute. What could you possibly offer?

We assure you that the little voice in your head is wrong.

Being a contributor doesn't just mean writing code. Equality important contributions include: writing or proof-reading documentation, suggesting or implementing tests, or even giving feedback about the project (including giving feedback about the contribution process). If you're coming to the project with fresh eyes, you might see the errors and assumptions that seasoned contributors have glossed over. If you can write any code at all, you can contribute code to open source. We are constantly trying out new skills, making mistakes, and learning from those mistakes. That's how we all improve and we are happy to help others learn.

This disclaimer was adapted from the MetPy project.

License

This is free software: you can redistribute it and/or modify it under the terms of the BSD 3-clause License. A copy of this license is provided in LICENSE.txt.

sphinx_gmt's People

Contributors

Stargazers

Watchers

Forkers

simrit1

sphinx_gmt's Issues

Rename to extension to gmtplot

The name of the module gmtplot is different from the actual directive gmt-plot. It would probably be easier if everything was gmtplot instead so we could include links to the API docs when mentioning the directive using :mod: links.

Convert gmt-plot directive to a rst snippet instead of HTML

If I understand the codes correctly, this extension convert gmt-plot directive to an HTML snippet using a Jinja template.

I think it's better to convert gmt-plot directive to a rst snippet.

.. gmt-plot::
    :figure: example_02.png
    
    gmt begin map ps
    gmt ...
    gmt end

should be equivalent to:

.. figure:: images/xxx.png
   :options:

.. code-block::
    
   gmt begin map pdf
   gmt ...
   gmt end

This is exactly how the matplotlib's plot directive does (see https://github.com/matplotlib/matplotlib/blob/f93222a555160bf967f02dae42cce39a03384774/lib/matplotlib/sphinxext/plot_directive.py#L348).

Option to hide the code

Some plots the GMT docs are generated by code but the code isn't included. This should be an option for the extension and there should still be a link to the code even if the code is hidden in the rst (#4).

Include code from a script

Right now the extension only allows inline code. It would be good if the code can be loaded from a script.

Include link to see the source

There should be a link to the source file for plots that are included from a script (#3)

The gmtplot directive no longer works for PyGMT output

Full code that generated the error

.. gmtplot::
    :language: python

    import pygmt
	  
	fig = pygmt.Figure()
	fig.coast(projection="G10/52/12c", region="g", frame="g", land="gray")
	fig.show()

Full error message

Exception occurred:
  File "/Users/seisman/OSS/gmt/sphinx_gmt/sphinx_gmt/gmtplot.py", line 262, in eval_python
    catch_display.output.data
AttributeError: 'NoneType' object has no attribute 'data'

The exceptions are most likely due to the redesign of the PyGMT's Figure.show() method in GenericMappingTools/pygmt#529. The main differences between the old and new Figure.show() method is that, the new Figure.show() method no longer returns the image.

Add support to run commands saved in scripts

@leouieda This sphinx extension is so cool. It's almost what I expect.

Currently, the commands for GMT plots must be written in the RST file. It would be better if this extension can run commands in a script, then insert the generated plot. This is what matplotlib can do (https://matplotlib.org/sampledoc/extensions.html#inserting-matplotlib-plots). The syntax may be look like this:

.. gmt-plot: scripts/plot-example.sh
    :figure: plot-example.png

Rename the project

pip search sphinx returns a list of packages related to sphinx. It seems most sphinx extensions have a name sphinx-xxx.

sphinx-advanced
Sphinx-Julia
sphinx-epytext
sphinx-tabs
sphinx-git
sphinx-sitemap
sphinx-boost
tachyonic-sphinx
sphinx-autorun
sphinx-graphiql
sphinx-csharp
sphinx-serve
sphinx-websequencediagrams
catkin-sphinx
sphinx-navtree
sphinx-nose
schemadisplay-sphinx
sphinx-server
sphinx-icontract
sphinx-refdoc
sphinx-confluence
zuul-sphinx
sphinx-jsonschema
sphinx-tsegsearch
sphinx-fortran
sphinx-scruffy
sphinx-prompt
sphinx-markdown
dragon-sphinx
sphinx-autoapi
sphinx-theme
sphinx-reload
anarchy-sphinx
tsuru-sphinx
sphinx-jsondomain
sphinx-a4doc
sphinx-JDLinker
sphinx-gallery
allanc-sphinx
sphinx-vlaamsecodex
sphinx-swagger
sphinx-elasticsearch
sphinx-revealjs
sphinx-astropy
sphinx-asciidoc
sphinx-testing
sphinx-click
sphinx-javalink
sphinx-tosca
sphinx-patchqueue
sphinx-pdj-theme
sphinx-simulink
sbo-sphinx
sphinx-lua
sphinx-nbexamples
sphinx-intl
django-sphinx
sphinx-argparse
sphinx-js
sphinx-view
sphinx-pyreverse
sphinx-issues
sphinxcontrib-getstart-sphinx
sphinx-stylo
sphinx-paramlinks
sphinx-links
sphinx-measurement
sphinx-dust
sphinx-hwt
sphinx-multibuild
sphinx-automodapi
pytest-sphinx
sphinx-autorun-ebs
jupyter-sphinx-theme
sphinx-autorun-ng
sphinx-glpi-theme
epfl-sphinx-theme
sphinx-guillotina-theme
sphinx-readable-theme
sphinx-rigado-extensions
sphinx-typlog-theme
hachibee-sphinx-theme
sphinx-bootstrap-theme
sphinx-quickstart-plus
zerovm-sphinx-theme
sphinx-rigado-theme
sphinx-compas-theme
sphinx-nameko-theme
dask-sphinx-theme
oe-sphinx-theme
sphinx-opnfv-theme
pytorch-sphinx-theme
sphinx-kml
travis-sphinx
sphinx-me
sphinx-catalystcloud-theme
sphinx-zon-theme
sphinx-ustack-theme
sphinx-gettext-helper
nengo-sphinx-theme

Maybe we can rename the project to sphinx-gmt.

Don't show the images even "gmt end show" is used

Just like what we do to the pygmt fig.show(), we should also deal with gmt end show in bash scripts.