It would be great if users could directly run our examples in the documentation, or, if we could auto-ish build jupyter notebooks from our .rst files.
I currently am building an example in pysatMadrigal, but also here. In the future, if one changes, the other won't automatically. Examples are good, but low technical debt is also good.
-
We could make our existing doc examples jupyter notebooks within the docs. https://jupyter-sphinx.readthedocs.io/en/latest/
We'd have to change all the instances of .. code:: in the .rst files to .. jupyter-execute:: The potential downside is I think RTD would then actually have to run all of our code to build the docs, which may involve downloading data.
-
Found a package that claims to couple with Sphinx to produce Jupyter notebooks. https://github.com/QuantEcon/sphinxcontrib-jupyter The code is in a code block but with a leading ```python so it fails when run. So close here but not quite right.
-
There are potentially options for converting existing docs to .ipynb. jupytext offers such a service, however, it doesn't support .rst but rather .myst . I ran jupytext on my DMSP example and it was a no go. It ran, but the .. code:: section wasn't treated as code. Everything gets loaded up into a big text type cell. There may be workarounds, like, auto translate .rst to .md first?
It would be great if users could directly run our examples in the documentation, or, if we could auto-ish build jupyter notebooks from our .rst files.
I currently am building an example in pysatMadrigal, but also here. In the future, if one changes, the other won't automatically. Examples are good, but low technical debt is also good.
We could make our existing doc examples jupyter notebooks within the docs. https://jupyter-sphinx.readthedocs.io/en/latest/
We'd have to change all the instances of
.. code::in the .rst files to.. jupyter-execute::The potential downside is I think RTD would then actually have to run all of our code to build the docs, which may involve downloading data.Found a package that claims to couple with Sphinx to produce Jupyter notebooks. https://github.com/QuantEcon/sphinxcontrib-jupyter The code is in a code block but with a leading ```python so it fails when run. So close here but not quite right.
There are potentially options for converting existing docs to .ipynb. jupytext offers such a service, however, it doesn't support .rst but rather .myst . I ran jupytext on my DMSP example and it was a no go. It ran, but the
.. code::section wasn't treated as code. Everything gets loaded up into a big text type cell. There may be workarounds, like, auto translate .rst to .md first?