Leveraging examples in package documentation

[rstoneback]

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?

[rstoneback]

Friendly ping @aburrell since this could involve a couple pulls I've requested review on.

[aburrell]

Uggg, I might not be the person to ping on this 😝 I think we should not change our docs.

I know there's a place for these executable tutorials, but I always found them hard to use and never wanted to "just run things", since there was no guarantee it would work the same for me locally or be relevant for my slightly different situation. My view is that these are best reserved for published examples, since you want them to always be the same.

[rstoneback]

Good to know. I was really hoping we could have our docs and make them tutorials too. Doesn't look like the packages are quite there yet.