Add sphinx extension myst-nb to enable writing executable Markdown notebooks (#3379)

* Add sphinx extension myst-nb and remove myst-parser
* Exclude .ipynb and .py files generated by sphinx-gallery
* Change install.md to be a notebook format and insert the output image into the document
* Split the test script into two separate cells

Author: seisman

.github/workflows/ci_docs.yml

@@ -107,7 +107,7 @@ jobs:
             build
             make
             pip
-            myst-parser
+            myst-nb
             panel
             sphinx
             sphinx-autodoc-typehints

ci/requirements/docs.yml

@@ -22,7 +22,7 @@ dependencies:
     - make
     - pip
     # Dev dependencies (building documentation)
-    - myst-parser
+    - myst-nb
     - panel
     - sphinx
     - sphinx-autodoc-typehints

doc/conf.py

@@ -24,7 +24,7 @@
 )
 
 extensions = [
-    "myst_parser",
+    "myst_nb",
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
     "sphinx.ext.coverage",
@@ -153,7 +153,21 @@
 
 # Sphinx project configuration
 templates_path = ["_templates"]
-exclude_patterns = ["_build", "**.ipynb_checkpoints"]
+exclude_patterns = [
+    "_build",
+    "**.ipynb_checkpoints",
+    # Workaround from https://github.com/executablebooks/MyST-NB/issues/363 to prevent
+    # myst-nb from parsing the .ipynb and .py files generated by sphinx-gallery.
+    "gallery/**.ipynb",
+    "tutorials/**.ipynb",
+    "get_started/**.ipynb",
+    "projections/**.ipynb",
+    "gallery/**.py",
+    "tutorials/**.py",
+    "get_started/**.py",
+    "projections/**.py",
+]
+
 source_suffix = ".rst"
 needs_sphinx = "1.8"
 # The encoding of source files.

doc/install.md

@@ -1,3 +1,7 @@
+---
+file_format: mystnb
+---
+
 # Installing
 
 ## Quickstart
@@ -233,16 +237,21 @@ from Python.
 To ensure that PyGMT and its dependencies are installed correctly, run the following
 in your Python interpreter:
 
-```python
+```{code-cell} ipython
+---
+tags: [hide-output]
+---
+
 import pygmt
 pygmt.show_versions()
+```
 
+```{code-cell} ipython
 fig = pygmt.Figure()
 fig.coast(projection="N15c", region="g", frame=True, land="tan", water="lightblue")
 fig.text(position="MC", text="PyGMT", font="80p,Helvetica-Bold,red@75")
 fig.show()
 ```
-![pygmt-get-started](https://github.com/GenericMappingTools/pygmt/assets/3974108/f7f51484-8640-4b58-ae5b-6c71e7150f7a){.align-center width="70%"}
 
 You should see a global map with land and water masses colored in tan and lightblue
 respectively. On top, there should be the semi-transparent text "PyGMT". If the

environment.yml

@@ -34,7 +34,7 @@ dependencies:
     - pytest-doctestplus
     - pytest-mpl
     # Dev dependencies (building documentation)
-    - myst-parser
+    - myst-nb
     - panel
     - sphinx
     - sphinx-autodoc-typehints