-
Notifications
You must be signed in to change notification settings - Fork 219
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Add metadata at the top so that myst-nb can recognize it as a MyST notebook.
doc/install.md
Outdated
--- | ||
tags: [remove-stdout] | ||
mystnb: | ||
image: center | ||
--- |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
---
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()
.
@@ -242,7 +252,6 @@ fig.coast(projection="N15c", region="g", frame=True, land="tan", water="lightblu | |||
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%"} |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Can these be more specific to point to a specific folder instead of using **
?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Done in 90bb110.
doc/install.md
Outdated
```{code-cell} ipython | ||
--- | ||
tags: [remove-stdout] | ||
--- | ||
|
||
import pygmt | ||
pygmt.show_versions() | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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-output
tag (see https://myst-nb.readthedocs.io/en/v0.13.2/use/hiding.html#hide-code-cells).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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-nb
to 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.md
file 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-nb
extension 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-parser
extension is removed because it's required bymyst-nb
and is automatically enabled bymyst-nb
.myst-nb
extension is necessary for writing documentation that needs images. For example, an image is needed to explain justification codes well.myst-nb
is one of the subprojects of The Executable Books Project. We're also using theirsphinx-copybutton
andsphinx-design
extensions. 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.