Skip to content

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

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.

Sign up for GitHub

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

Merged
seisman merged 9 commits into from
Aug 12, 2024
Merged

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

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
d0059c9
Add sphinx extension myst-nb and remove myst-parser
seisman Aug 6, 2024
fba97ba
Exclude .ipynb and .py files generated by sphinx-gallery
seisman Aug 6, 2024
48951ba
Change install.md to be a notebook format and insert the output image…
seisman Aug 6, 2024
c7324b1
Merge branch 'main' into doc/mystnb
seisman Aug 7, 2024
a30f2ce
Merge branch 'main' into doc/mystnb
seisman Aug 11, 2024
c9a8e90
Merge branch 'main' into doc/mystnb
seisman Aug 12, 2024
90bb110
Be more specific about which directories to ignore
seisman Aug 12, 2024
609d759
Split the test script into two separate cells
seisman Aug 12, 2024
7a38068
Fix the exclude_patterns parameter to avoid warnings
seisman Aug 12, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/ci_docs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -107,7 +107,7 @@ jobs:
build
make
pip
myst-parser
myst-nb
panel
sphinx
sphinx-autodoc-typehints
Expand Down
2 changes: 1 addition & 1 deletion ci/requirements/docs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ dependencies:
- make
- pip
# Dev dependencies (building documentation)
- myst-parser
- myst-nb
- panel
- sphinx
- sphinx-autodoc-typehints
Expand Down
11 changes: 9 additions & 2 deletions doc/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@
)

extensions = [
"myst_parser",
"myst_nb",
"sphinx.ext.autodoc",
"sphinx.ext.autosummary",
"sphinx.ext.coverage",
Expand Down Expand Up @@ -153,7 +153,14 @@

# 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.
"**/*.ipynb",
"**/*.py",
Copy link
Member

@weiji14 weiji14 Aug 11, 2024

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

@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 90bb110.

]
source_suffix = ".rst"
needs_sphinx = "1.8"
# The encoding of source files.
Expand Down
11 changes: 9 additions & 2 deletions doc/install.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
---
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.

Add metadata at the top so that myst-nb can recognize it as a MyST notebook.

file_format: mystnb
---

# Installing

## Quickstart
Expand Down Expand Up @@ -233,7 +237,11 @@ from Python.
To ensure that PyGMT and its dependencies are installed correctly, run the following
in your Python interpreter:

```python
```{code-cell} ipython
---
tags: [remove-stdout]
---

import pygmt
pygmt.show_versions()

Copy link
Member

@weiji14 weiji14 Aug 11, 2024

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 •
edited
Loading

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

@weiji14 weiji14 Aug 12, 2024

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 😆

Expand All @@ -242,7 +250,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

@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.

No need to include the external image.


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
Expand Down
2 changes: 1 addition & 1 deletion environment.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ dependencies:
- pytest-doctestplus
- pytest-mpl
# Dev dependencies (building documentation)
- myst-parser
- myst-nb
- panel
- sphinx
- sphinx-autodoc-typehints
Expand Down