Add sphinx extension myst-nb to enable writing executable Markdown notebooks#3379
Add sphinx extension myst-nb to enable writing executable Markdown notebooks#3379
Conversation
myst-nb depends on myst-parser.
| @@ -1,3 +1,7 @@ | |||
| --- | |||
There was a problem hiding this comment.
Add metadata at the top so that myst-nb can recognize it as a MyST notebook.
| --- | ||
| tags: [remove-stdout] | ||
| mystnb: | ||
| image: center | ||
| --- |
There was a problem hiding this comment.
---
tags: [remove-stdout]
---
These lines are cell-level metadata for controlling the format of the output. Usually it's not necessary. Here remove-stdout is necessary to hide the long output from pygmt.show_versions().
| fig.text(position="MC", text="PyGMT", font="80p,Helvetica-Bold,red@75") | ||
| fig.show() | ||
| ``` | ||
| {.align-center width="70%"} |
There was a problem hiding this comment.
No need to include the external image.
… into the document
doc/conf.py
Outdated
| # 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. | ||
| "**/*.ipynb", | ||
| "**/*.py", |
There was a problem hiding this comment.
Can these be more specific to point to a specific folder instead of using **?
| ```{code-cell} ipython | ||
| --- | ||
| tags: [remove-stdout] | ||
| --- | ||
|
|
||
| import pygmt | ||
| pygmt.show_versions() | ||
|
|
There was a problem hiding this comment.
These lines are cell-level metadata for controlling the format of the output. Usually it's not necessary. Here remove-stdout is necessary to hide the long output from pygmt.show_versions().
Would it be nicer to actually show the output of pygmt.show_versions() actually? Suggestion to:
- Split into two code blocks, one for
pygmt.show_versions()and one forfig = pygmt.Figure()below - Collapse the output of
pygmt.show_versions()in a dropdown using thehide-outputtag (see https://myst-nb.readthedocs.io/en/v0.13.2/use/hiding.html#hide-code-cells).
There was a problem hiding this comment.
Readthedocs is showing the PyGMT version as v0.1.dev64+g7a38068.d20240812, but I guess that's ok 😆
Description of proposed changes
This PR adds the Sphinx extension
myst-nbto enable executing code cells in a file and insert the output directly into the file. The file format can be (1) ReST; (2) Plain Markdown; (3) Jupyter Notebooks; (4) MyST text-based notebooks. See https://myst-nb.readthedocs.io/en/latest/authoring/basics.html for more details.The text-based MyST notebook is the most appealing format. To convert a plain Markdown file into a MyST notebook, we just need to do two things:
This PR also updates the
install.mdfile as an example showing how the extension works. In the installation guides, we provide a test script and include an external image (added in #3249) to show how the output looks like. It's not ideal since the image may be outdated when we update the test script. Themyst-nbextension can execute the codes and directly insert the output image below the codes, so the codes and the image are always consistent.Preview: https://pygmt-dev--3379.org.readthedocs.build/en/3379/install.html#testing-your-install
Notes:
myst-parserextension is removed because it's required bymyst-nband is automatically enabled bymyst-nb.myst-nbextension is necessary for writing documentation that needs images. For example, an image is needed to explain justification codes well.myst-nbis one of the subprojects of The Executable Books Project. We're also using theirsphinx-copybuttonandsphinx-designextensions. Maybe one day we should consider migrating to their Jupyter Book project, which is built on top of Sphinx and a collection of Sphinx extensions.