Render doctest block as code block #2
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Fixes `WARNING: `doctest_block` node not implemented`.
weiji14
added a commit
to weiji14/cog3pio
that referenced
this pull request
Jun 17, 2025
Figured out how to get doctest_block nodes working with a one-line change at jupyter-book/sphinx-ext-mystmd#2. Partially reverts 5d0ff56.
weiji14
added a commit
to weiji14/cog3pio
that referenced
this pull request
Jun 17, 2025
* ➕ Add jupyter-book
Create beautiful, publication-quality books and documents from computational content!
* 🌱 Initialize Jupyter Book 2 with MyST
Starting with a minimal Jupyter Book initialized with `jupyter book init`. Changed the `myst.yml` to use a proper title and description.
* 📝 Use sphinx-ext-mystmd to generate autodoc API reference
Move myst.yml to docs/ folder, and create a Sphinx configuration file at docs/conf.py. Docs are now built using `cd docs/ && sphinx-build --builder myst . _build/myst-asts && jupyter book start`.
Extensions used:
- `myst_parser` - Because the index page and API docs page in MyST instead of ReST
- `sphinx_ext_mystmd` - Allows Sphinx to build an `api.myst.json` file that can then be used by MyST-MD
- `sphinx.ext.autodoc` - Regular Sphinx extension to pull in documentation from docstrings
- `sphinx.ext.napolean` - Support for NumPy style docstrings
Note: needed to use {eval-rst} directive in API docs because https://myst-parser.readthedocs.io/en/latest/syntax/code_and_apis.html#sphinx-ext-autodoc says `sphinx.ext.autodoc` generates ReST only, and I didn't want to use `sphinx-autodoc2`.
* 💬 Indent doctest examples to render them as code blocks
Need to add a sentence, and then indent the code block by 4 spaces to it into a literal block (couldn't figure out syntax highlighting yet). Also taking the chance to properly update the docstrings, mentioning that read_geotiff only supports float32, and documenting the xy_coords method with more details.
* 💚 Don't run rustdoc tests on pyo3 modules
Fixes error with `cargo test` trying to run doctests in src/python/adapters.rs that are meant for Python, not Rust. Xref https://users.rust-lang.org/t/disabling-rustdoc-tests-for-module/50110/2
* 🎨 Use sphinx-ext-mystmd patch to unindent doctest blocks
Figured out how to get doctest_block nodes working with a one-line change at jupyter-book/sphinx-ext-mystmd#2. Partially reverts 5d0ff56.
weiji14
added a commit
to weiji14/cog3pio
that referenced
this pull request
Jun 23, 2025
Need to use an official PyPI released version in pyproject.toml, but still installing from jupyter-book/sphinx-ext-mystmd#2 in the docs/.readthedocs.yml file.
weiji14
added a commit
to weiji14/cog3pio
that referenced
this pull request
Jun 23, 2025
Need to use an official PyPI released version in pyproject.toml, but still installing from jupyter-book/sphinx-ext-mystmd#2 in the docs/.readthedocs.yml file.
weiji14
added a commit
to weiji14/cog3pio
that referenced
this pull request
Jun 23, 2025
Need to use an official PyPI released version in pyproject.toml, but still installing from jupyter-book/sphinx-ext-mystmd#2 in the docs/.readthedocs.yml file.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Fixes "WARNING:
doctest_blocknode not implemented". Re-using the same code fromliteral_blockhere:sphinx-ext-mystmd/src/sphinx_ext_mystmd/transform.py
Lines 418 to 420 in 51277db
For example, for my PR at weiji14/cog3pio#35 where I'm trying to render a NumPy-style docstring like this:
The rendering should look something like this:
Not sure yet how to add syntax highlighting, open to tips!