DOC: use Jupyter examples via nbsphinx gallery (geopandas#1731)

.gitignore

@@ -59,7 +59,6 @@ doc/_build/
 
 examples/nybb_*.zip
 
-doc/source/gallery
 doc/source/savefig
 doc/source/reference
 doc/source/docs/reference/api

doc/Makefile

@@ -41,7 +41,6 @@ help:
 clean:
 	-rm -rf $(BUILDDIR)/*
 	-rm -rf source/reference/*
-	-rm -rf source/gallery/*
 
 html:
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html

doc/environment.yml

@@ -1,35 +1,41 @@
 name: geopandas_docs
 channels:
-- conda-forge
+  - conda-forge
 dependencies:
-- python=3.7
-- pandas=1.0.1
-- shapely=1.7.0
-- fiona=1.8.13
-- pyproj=2.4.2.post1
-- rtree=0.9.4
-- geopy=1.21.0
-- matplotlib=3.1.3
-- mapclassify=2.2.0
-- sphinx=2.4.1
-- pydata-sphinx-theme=0.3.1
-- numpydoc=0.9.2
-- ipython=7.12.0
-- pillow=7.0.0
-- mock=3.0.5
-- cartopy=0.17.0
-- contextily=1.0rc2
-- rasterio=1.1.1
-- geoplot=0.4.0
-# 0.5.0 has a bug (https://github.com/sphinx-gallery/sphinx-gallery/issues/568)
-- sphinx-gallery=0.4.0
-- jinja2=2.11.1
-- doc2dash
-# specify additional dependencies to reduce solving for conda
-- gdal=3.0.4
-- libgdal=3.0.4
-- proj=6.3.0
-- geos=3.8.0
-- pip:
-  - myst-nb
-  - sphinx-toggleprompt
+  - python
+  - pandas
+  - shapely
+  - fiona
+  - pyproj
+  - rtree
+  - geopy
+  - matplotlib
+  - descartes
+  - mapclassify
+  - sphinx
+  - pydata-sphinx-theme
+  - numpydoc
+  - ipython
+  - pillow
+  - mock
+  - cartopy
+  - contextily
+  - rasterio
+  - geoplot
+  - sphinx-gallery
+  - jinja2
+  - doc2dash
+  # specify additional dependencies to reduce solving for conda
+  # - gdal=3.0.4
+  # - libgdal=3.0.4
+  # - proj=6.3.0
+  # - geos=3.8.0
+  - nbsphinx
+  - jupyter_client
+  - ipykernel
+  - myst-parser
+  - folium
+  - libpysal
+  - pip
+  - pip:
+      - sphinx-toggleprompt

doc/source/community/contributing.rst

@@ -247,27 +247,34 @@ install *GeoPandas*) by typing::
 6) Updating the Documentation
 -----------------------------
 
-*GeoPandas* documentation resides in the `doc` folder. Changes to the docs are
-make by modifying the appropriate file in the `source` folder within `doc`.
-*GeoPandas* docs use reStructuredText syntax, `which is explained here <http://www.sphinx-doc.org/en/stable/rest.html#rst-primer>`_
-and the docstrings follow the `Numpy Docstring standard <https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt>`_.
+*GeoPandas* documentation resides in the ``doc`` folder. Changes to the docs are make by
+modifying the appropriate file in the `source` folder within ``doc``. *GeoPandas* docs use
+mixture of reStructuredText syntax for ``rst`` files, `which is explained here
+<http://www.sphinx-doc.org/en/stable/rest.html#rst-primer>`_ and MyST syntax for ``md``
+files `explained here <https://myst-parser.readthedocs.io/en/latest/index.html>`_.
+The docstrings follow the `Numpy Docstring standard
+<https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt>`_. Some pages
+and examples are Jupyter notebooks converted to docs using `nbsphinx
+<https://nbsphinx.readthedocs.io/>`_. Jupyter notebooks should be stored without the output.
 
 Once you have made your changes, you may try if they render correctly by
 building the docs using sphinx. To do so, you can navigate to the `doc` folder
 and type::
 
     make html
 
-The resulting html pages will be located in `doc/build/html`. In case of any
-errors, you can try to use `make html` within a new environment based on
-environment.yml specification in the `doc` folder. Using conda::
+The resulting html pages will be located in ``doc/build/html``. In case of any errors, you
+can try to use ``make html`` within a new environment based on environment.yml
+specification in the ``doc`` folder. You may need to register Jupyter kernel as
+``geopandas_docs``. Using conda::
 
     conda env create -f environment.yml
     conda activate geopandas_docs
+    python -m ipykernel install --user --name geopandas_docs
     make html
 
-For minor updates, you can skip whole `make html` part as reStructuredText syntax
-is usually quite straightforward.
+For minor updates, you can skip whole ``make html`` part as reStructuredText and MyST
+syntax are usually quite straightforward.
 
 
 7) Submitting a Pull Request

doc/source/conf.py

@@ -29,7 +29,7 @@
 extensions = [
     "IPython.sphinxext.ipython_console_highlighting",
     "IPython.sphinxext.ipython_directive",
-    "sphinx_gallery.gen_gallery",
+    "sphinx_gallery.load_style",
     "sphinx.ext.autosummary",
     "sphinx.ext.intersphinx",
     "sphinx.ext.autodoc",
@@ -63,20 +63,10 @@ def setup(app):
 
 autosummary_generate = True
 
-# Sphinx gallery configuration
-sphinx_gallery_conf = {
-    "examples_dirs": ["../../examples"],
-    "filename_pattern": "^((?!sgskip).)*$",
-    "gallery_dirs": ["gallery"],
-    "doc_module": ("geopandas",),
-    "reference_url": {
-        "matplotlib": "http://matplotlib.org",
-        "numpy": "http://docs.scipy.org/doc/numpy",
-        "scipy": "http://docs.scipy.org/doc/scipy/reference",
-        "geopandas": None,
-    },
-    "backreferences_dir": "reference",
-}
+nbsphinx_execute = "always"
+nbsphinx_kernel_name = "geopandas_docs"
+nbsphinx_allow_errors = True
+
 # connect docs in other projects
 intersphinx_mapping = {"pyproj": ("http://pyproj4.github.io/pyproj/stable/", None)}
 # suppress matplotlib warning in examples
@@ -326,3 +316,19 @@ def setup(app):
 
 # How to display URL addresses: 'footnote', 'no', or 'inline'.
 # texinfo_show_urls = 'footnote'
+
+nbsphinx_prolog = r"""
+{% set docname = env.doc2path(env.docname, base=None) %}
+
+.. only:: html
+
+    .. role:: raw-html(raw)
+        :format: html
+
+    .. note::
+
+        | This page was generated from `{{ docname }}`__.
+        | Interactive online version: :raw-html:`<a href="https://mybinder.org/v2/gh/geopandas/geopandas/master?urlpath=lab/tree/doc/source/{{ docname }}"><img alt="Binder badge" src="https://mybinder.org/badge_logo.svg" style="vertical-align:text-bottom"></a>`
+
+        __ https://github.com/geopandas/geopandas/blob/master/doc/source/{{ docname }}
+"""