Sphinx extension for GMT/Python plots (#208)

Add a sphinx extension `gmt.sphinxext.gmtplot` to the package.
It enables the `gmt-plot` directive that executes the given code,
captures the output of `gmt.Figure.show` and stdout, and 
inserts them into the rst document.

Includes a plot in the front page and a page documenting the
extension. It also serves as a test for the extension.

The code is not tested with pytest. This could possibly be done
using [sphinx-testing](https://github.com/sphinx-doc/sphinx-testing).

Fixes #129

Author: leouieda

.github/readme-example.png

@@ -14,14 +14,38 @@
     </p>
 
     <p align="center">
+    <a href="http://try.gmtpython.xyz/">Online Demo</a> |
     <a href="https://www.gmtpython.xyz">Documentation</a> |
-    <a href="https://www.gmtpython.xyz/latest/install.html">Install</a> |
-    <a href="https://www.gmtpython.xyz/latest/tutorials">Tutorials</a> |
-    <a href="https://www.gmtpython.xyz/latest/api">API</a> |
+    <a href="https://github.com/GenericMappingTools/gmt-python">Source Code</a> |
     <a href="https://gitter.im/GenericMappingTools/gmt-python">Contact</a>
     </p>
 
 
+.. code:: python
+
+    import gmt
+
+    # Load sample earthquake data in a pandas.DataFrame
+    quakes = gmt.datasets.load_usgs_quakes()
+
+    # Load the builtin Earth relief grid as an xarray.DataArray.
+    relief = gmt.datasets.load_earth_relief(resolution="30m")
+
+    # The Figure object controls all plotting functions
+    fig = gmt.Figure()
+    # Setup a map with a global region, a Mollweide projection, and automatic ticks
+    fig.basemap(region="g", projection="W200/8i", frame=True)
+    # Plot the Earth relief grid in pseudo-color.
+    fig.grdimage(relief, cmap="geo")
+    # Plot earthquakes as circles. Size maps to magnitude and color to depth.
+    fig.plot(x=quakes.longitude, y=quakes.latitude, sizes=0.01*2**quakes.mag,
+             color=quakes.depth/quakes.depth.max(), cmap="viridis", style="cc")
+    # Show a preview of the image (inline if in a Jupyter notebook).
+    fig.show()
+
+.. image:: .github/readme-example.png
+
+
 Disclaimer
 ----------
 
@@ -39,52 +63,35 @@ Getting started
 ---------------
 
 1. Try an online demo at `try.gmtpython.xyz <http://try.gmtpython.xyz>`__
-2. `Install <https://www.gmtpython.xyz/latest/install.html>`__ (tested and working on
-   Linux and OSX)
+2. `Install <https://www.gmtpython.xyz/latest/install.html>`__ (Linux and Mac)
 3. Follow the `Tutorials <https://www.gmtpython.xyz/latest/tutorials>`__.
-4. Take a look at the `API <https://www.gmtpython.xyz/latest/api>`__ for a list of
-   modules that are already available.
-
-
-About
------
-
-Watch the `Scipy 2017 talk about GMT/Python <https://github.com/GenericMappingTools/scipy2017>`__
-for more information about the history and goals of the project:
-
-.. image:: https://raw.githubusercontent.com/GenericMappingTools/gmt-python/master/doc/_static/scipy2017-youtube-thumbnail.png
-    :alt: YouTube recording of the Scipy2017 talk.
-    :target: https://www.youtube.com/watch?v=93M4How7R24
+4. Take a look at the `API <https://www.gmtpython.xyz/latest/api>`__ to see what is
+   available.
 
 
 Project goals
 -------------
 
-* Build a modern Pythonic API that appeals to Python programmers who want to
-  use GMT.
-* Implement readable and explicit aliases for the GMT command-line arguments
-  (``region`` instead of ``R``, ``projection`` instead of ``J``, etc).
-* Use the new `GMT modern mode
-  <http://gmt.soest.hawaii.edu/projects/gmt/wiki/Modernization>`__ for
-  simplified execution and figure generation.
-* Interface with the GMT C API directly using
-  `ctypes <https://docs.python.org/3/library/ctypes.html>`__ (no system calls).
-* Integration with the `Jupyter notebook <http://jupyter.org/>`__ to display
-  plots and maps inline.
-* Input and output using Python native containers: numpy ``ndarray`` or pandas
-  ``DataFrame`` for data tables and `xarray <http://xarray.pydata.org>`__
-  ``Dataset`` for netCDF grids.
+* Make GMT more accessible to new users.
+* Build a Pythonic API for GMT.
+* Interface with the GMT C API directly using ctypes (no system calls).
+* Support for rich display in the Jupyter notebook.
+* Integration with the Scipy stack: numpy.ndarray or pandas.DataFrame for data tables
+  and xarray.DataArray for grids.
 
 
 Contacting Us
 -------------
 
-* Most discussion happens `on Github <https://github.com/GenericMappingTools/gmt-python>`__.
-  Feel free to `open an issue
-  <https://github.com/GenericMappingTools/gmt-python/issues/new>`__ or comment
-  on any open issue or pull request.
-* We have `chat room on Gitter <https://gitter.im/GenericMappingTools/gmt-python>`__
+* Most discussion happens `on Github
+  <https://github.com/GenericMappingTools/gmt-python>`__. Feel free to `open an issue
+  <https://github.com/GenericMappingTools/gmt-python/issues/new>`__ or comment on any
+  open issue or pull request.
+* We have a `chat room on Gitter <https://gitter.im/GenericMappingTools/gmt-python>`__
   where you can ask questions and leave comments.
+* This project is released with a `Contributor Code of Conduct
+  <https://github.com/GenericMappingTools/gmt-python/blob/master/CODE_OF_CONDUCT.md>`__.
+  By participating in this project you agree to abide by its terms.
 
 
 Contributing
@@ -93,40 +100,36 @@ Contributing
 Code of conduct
 +++++++++++++++
 
-Please note that this project is released with a
-`Contributor Code of Conduct <https://github.com/GenericMappingTools/gmt-python/blob/master/CODE_OF_CONDUCT.md>`__.
+Please note that this project is released with a `Contributor Code of Conduct
+<https://github.com/GenericMappingTools/gmt-python/blob/master/CODE_OF_CONDUCT.md>`__.
 By participating in this project you agree to abide by its terms.
 
 Contributing Guidelines
 +++++++++++++++++++++++
 
-Please read our
-`Contributing Guide <https://github.com/GenericMappingTools/gmt-python/blob/master/CONTRIBUTING.md>`__
-to see how you can help and give feedback.
+Please read our `Contributing Guide
+<https://github.com/GenericMappingTools/gmt-python/blob/master/CONTRIBUTING.md>`__ 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?
+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.
+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 <https://github.com/Unidata/MetPy>`__.
@@ -135,24 +138,19 @@ That's how we all improve and we are happy to help others learn.
 Related projects
 ----------------
 
-* `GMT.jl <https://github.com/GenericMappingTools/GMT.jl>`__ -- A Julia wrapper
+* `GMT.jl <https://github.com/GenericMappingTools/GMT.jl>`__: A Julia wrapper for GMT.
+* `gmtmex <https://github.com/GenericMappingTools/GMT.jl>`__: A Matlab/Octave wrapper
   for GMT.
-* `gmtmex <https://github.com/GenericMappingTools/GMT.jl>`__ -- A Matlab/Octave
-  wrapper for GMT.
 
 Other Python wrappers for GMT:
 
-* `gmtpy <https://github.com/emolch/gmtpy>`__ by
-  `Sebastian Heimann <https://github.com/emolch>`__
-* `pygmt <https://github.com/ian-r-rose/pygmt>`__ by
-  `Ian Rose <https://github.com/ian-r-rose>`__
-* `PyGMT <https://github.com/glimmer-cism/PyGMT>`__  by
-  `Magnus Hagdorn <https://github.com/mhagdorn>`__
+* `gmtpy <https://github.com/emolch/gmtpy>`__ by `Sebastian Heimann <https://github.com/emolch>`__
+* `pygmt <https://github.com/ian-r-rose/pygmt>`__ by `Ian Rose <https://github.com/ian-r-rose>`__
+* `PyGMT <https://github.com/glimmer-cism/PyGMT>`__  by `Magnus Hagdorn <https://github.com/mhagdorn>`__
 
 
 License
 -------
 
-gmt-python 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``.
+GMT/Python 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``.

README.rst

@@ -15,6 +15,29 @@ h1 {
     font-size: 200%;
 }
 
+.gmtplot-output {
+    width: 100%;
+    overflow: auto;
+}
+
+.gmtplot-output img {
+    max-width: 700px;
+    width: 100%;
+}
+
+.gmtplot-output pre {
+    color: #888888;
+}
+
+.gmtplot-output-figure {
+    margin-bottom: 50px;
+}
+
+.rst-content img {
+    max-width: 700px;
+    width: 100%;
+}
+
 .sidebar-title {
     margin-top: 10px;
     margin-bottom: 0px;
@@ -57,8 +80,9 @@ h1 {
 
 .wy-menu-vertical header, .wy-menu-vertical p.caption {
     font-size: 90%;
-    font-weight: normal;
+    font-weight: bold;
     color: #eeeeee;
+    letter-spacing: 0.12em;
 }
 
 .wy-nav-content {
@@ -79,11 +103,6 @@ h1 {
     font-size: 14px;
 }
 
-.rst-content img {
-    max-width: 450px;
-    width: 100%;
-}
-
 .source-link {
     float: right;
 }

doc/_static/front-page-example.png

@@ -18,9 +18,9 @@
     'sphinx.ext.doctest',
     'sphinx.ext.viewcode',
     'sphinx.ext.extlinks',
-    'sphinx.ext.intersphinx',
     'numpydoc',
     'nbsphinx',
+    'gmt.sphinxext.gmtplot',
 ]
 
 # Autosummary pages will be generated by sphinx-autogen instead of sphinx-build
@@ -83,13 +83,6 @@
     'github_version': 'master',
 }
 
-# intersphinx
-intersphinx_mapping = {
-    'python': ('https://docs.python.org/3/', None),
-    'numpy': ('https://docs.scipy.org/doc/numpy/', None),
-    'pandas': ('http://pandas.pydata.org/pandas-docs/stable/', None),
-}
-
 # Load the custom CSS files (needs sphinx >= 1.6 for this to work)
 def setup(app):
     app.add_stylesheet("style.css")