Skip to content
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

Merged
merged 9 commits into from
Aug 12, 2024

Conversation

seisman
Copy link
Member

@seisman seisman commented Aug 6, 2024

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:

  1. Add metadata at the top of a markdown file. The simplest example is:
---
file_format: mystnb
---
  1. Write codes using the following syntax
```{code-cell}
a = "This is some"
b = "Python code!"
print(f"{a} {b}")
```

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. The myst-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:

  1. The myst-parser extension is removed because it's required by myst-nb and is automatically enabled by myst-nb.
  2. The myst-nb extension is necessary for writing documentation that needs images. For example, an image is needed to explain justification codes well.
  3. This extension can't replace sphinx-gallery now, but maybe it can in the future (xref Enable thumbnail galleries of notebooks executablebooks/MyST-NB#396)
  4. myst-nb is one of the subprojects of The Executable Books Project. We're also using their sphinx-copybutton and sphinx-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.

@seisman seisman changed the title Add sphinx extension myst-nb to enable executing code cells in Markdown and insert the output directly Add sphinx extension myst-nb to enable writing executable Markdown notebooks Aug 6, 2024
@@ -1,3 +1,7 @@
---
Copy link
Member Author

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
Comment on lines 241 to 243
---
tags: [remove-stdout]
mystnb:
image: center
---
Copy link
Member Author

@seisman seisman Aug 6, 2024

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%"}
Copy link
Member Author

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.

@seisman seisman added the documentation Improvements or additions to documentation label Aug 6, 2024
@seisman seisman added this to the 0.13.0 milestone Aug 6, 2024
@seisman seisman added the needs review This PR has higher priority and needs review. label Aug 6, 2024
@seisman seisman requested a review from a team August 11, 2024 04:43
doc/conf.py Outdated
Comment on lines 159 to 162
# 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",
Copy link
Member

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 **?

Copy link
Member Author

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
Comment on lines 240 to 247
```{code-cell} ipython
---
tags: [remove-stdout]
---

import pygmt
pygmt.show_versions()

Copy link
Member

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:

  1. Split into two code blocks, one for pygmt.show_versions() and one for fig = pygmt.Figure() below
  2. Collapse the output of pygmt.show_versions() in a dropdown using the hide-output tag (see https://myst-nb.readthedocs.io/en/v0.13.2/use/hiding.html#hide-code-cells).

Copy link
Member Author

@seisman seisman Aug 12, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done in 609d759 and 7a38068 and looks better.

Copy link
Member

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 😆

@seisman seisman removed the needs review This PR has higher priority and needs review. label Aug 12, 2024
@seisman seisman merged commit 7906307 into main Aug 12, 2024
9 checks passed
@seisman seisman deleted the doc/mystnb branch August 12, 2024 08:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants