DOC/DX: add documentation for interactive examples and their maintenance

[agriyakhetarpal]

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 DOC: Add >>> import numpy as np stubs everywhere #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 the try_examples.json file 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 (INFO: Old SciPy version in embedded Jupyterlite notebooks? scipy/scipy#20918) and NumPy (Update to NumPy v2 and bump versions for several dependent packages pyodide/pyodide#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: DOC/DEV: add docs for enabling interactive examples scipy/scipy#20843, and
• interactive documentation for SciPy was (previously) enabled in DOC: Add support for interactive examples with jupyterlite-sphinx scipy/scipy#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:

1. https://github.com/numpy/numpy/blob/main/doc/RELEASE_WALKTHROUGH.rst, and
2. https://numpy.org/devdocs/dev/howto-docs.html#docstring-intro, and
3. 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.

[rootsmusic]

some of these points I have mentioned above could be better placed in part in a SPEC document

@agriyakhetarpal ICYMI Quansight-Labs/czi-scientific-python-mgmt#17

[agriyakhetarpal]

Thanks for the ping, @rootsmusic – it is indeed on my radar and a public draft for "SPEC 14 – Interactive Documentation" is slated to come soon (within this month, most likely). We could close out this issue with that, as some surrounding documentation also exists in SciPy now: scipy/scipy#22385.