Sphinx Extension

We provide a Sphinx extension for including GMT/Python figures in your documentation. The extension defines the gmt-plot directive that will take execute the given code and insert the generated figure into the document.

For example, the following rst code:

.. gmt-plot::

    import gmt
    fig = gmt.Figure()
    fig.basemap(region="g", projection="W0/10i", frame="afg")
    fig.show()

will be rendered into the following in the compiled HTML pages:

import gmt
fig = gmt.Figure()
fig.basemap(region="g", projection="W0/10i", frame="afg")
fig.show()

The last statement of the code-block should contain a call to gmt.Figure.show. Anything printed to STDOUT will be captured and included between the figure and the code. For example:

print("The variables from the previous block are preserved.")
fig.coast(land="gray")
fig.show()
The variables from the previous block are preserved.

The HTML rich display features that work in Jupyter notebooks also work for the extension:

quakes = gmt.datasets.load_usgs_quakes()

fig2 = gmt.Figure()
fig2.plot(x=quakes.longitude, y=quakes.latitude, region=[-180, 180, -90, 90],
          projection="X10id", color="yellow", style="c0.2c", pen="black")
fig2.show(method="globe")
Your browser does not support HTML5 Canvas.

Installing

The extension comes with GMT/Python. All you have to do is enable it in your conf.py file:

extensions = [
    ...,
    "gmt.sphinxext.gmtplot",
]

However, you will need to have IPython installed for the extension to work.

Options

The directive has the following options:

.. gmt-plot::
    :width: size   # Set the width of the image (should contain a unit, like 400px)
    :center:       # If set, will center the output image
    :hide-code:    # If set, then hide the code and only show the plot
    :namespace:    # Specify a plotting namespace that is persistent within the page