DOC/DX: add documentation for interactive examples and their maintenance
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 32.8k
- Forks
- 12.8k
- Avg merge
- 1d 7h
- Merged PRs (30d)
- 197
Description
Issue with current documentation:
This is a short follow-up issue stemmed off from gh-26745 (review) and gh-26745 (comment) – once said PR is merged, the NumPy documentation for contributors and core developers should mention how to enable interactive examples with jupyterlite-sphinx. This issue aims to track that process, with the information to be added pertaining to:
- interactive documentation and best practices on writing it, enabling it, and ensuring that it works as intended:
- particularly, this means we should instruct docs contributors to write self-contained examples in the docstrings, as done in gh-26814
jupyterlite-sphinx, links to its documentation, and instructions on how to enable/disable interactive examples on certain sections for the development version or released versions of the documentation via suitable modifications in thetry_examples.jsonfile for features or API sections that are not available with in-tree Pyodide wheels; and- how updates in the documentation should be synced with updates from Pyodide upstream, new minor releases for which usually carry package updates, usually updating core packages such as SciPy (https://github.com/scipy/scipy/issues/20918) and NumPy (https://github.com/pyodide/pyodide/pull/4925).
- this is tied in with rebuilding the documentation for a particular version present at https://github.com/numpy/doc. Instructions for doing so are available in the repository's README.
Additional context
- Please refer to this PR where updates to the SciPy documentation were made: https://github.com/scipy/scipy/pull/20843, and
- interactive documentation for SciPy was (previously) enabled in https://github.com/scipy/scipy/pull/20019
cc: @melissawm, @rgommers, @steppi
Idea or request for content:
My idea is that the most appropriate place(s) to add documentation related to this should be in these pages and cross-linked with each other, based on the last point above:
- https://github.com/numpy/numpy/blob/main/doc/RELEASE_WALKTHROUGH.rst, and
- https://numpy.org/devdocs/dev/howto-docs.html#docstring-intro, and
- perhaps a "Pyodide" section nearby https://numpy.org/devdocs/dev/howto_build_docs.html#instructions?
Additionally, some suggestions from @melissawm are as follows:
I would either link or get inspiration from scipy.github.io/devdocs/dev/core-dev/index.html#wrapping-up (for the release guide) and the "Interactive documentation" section on scipy.github.io/devdocs/dev/contributor/rendering_documentation.html#rendering-documentation-locally-with-sphinx
With some guidelines set on the interactive documentation goal and once gh-26745 gets merged, we could soon start looking at enabling interactivity in the "User Guide" pages and potentially for https://numpy.org/numpy-tutorials/ in the future. IMO, some of these points I have mentioned above could be better placed in part in a SPEC document rather than completely in the NumPy documentation, though.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with doc/RELEASE_WALKTHROUGH.rst and the contributor pages linked in the issue, then compare the SciPy documentation references. Document jupyterlite-sphinx, self-contained examples, try_examples.json settings, Pyodide synchronization, and rebuilding versioned documentation using the numpy/doc README; done means these workflows are covered and cross-linked.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- developer-experience, documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100