search

cameronraysmith / nbsphinx-template

This is a template for using https://github.com/spatialaudio/nbsphinx.
https://cameronraysmith.net/nbsphinx-template
BSD 3-Clause "New" or "Revised" License
2 stars 0 forks source link

commit notebooks without outputs? #2

Open mgeier opened 3 years ago

mgeier commented 3 years ago

I think it is a better practice to remove outputs before committing to Git and then execute the notebooks on readthedocs.org (or a similar service).

What about removing the outputs and instead adding an example config for RTD?

I guess this wouldn't hurt, right?

cameronraysmith commented 3 years ago

Notebooks without outputs should be executed by github actions here, https://github.com/cameronraysmith/nbsphinx-template/blob/cb1cbdb6b8484315860e5aac1045c2e46193168b/.github/workflows/default.yml#L19 which should occur within an environment including packages from requirements.txt in the source directory according to https://github.com/ammaraskar/sphinx-action#how-to-use. I will eventually expand on this in a better https://github.com/cameronraysmith/nbsphinx-template/blob/cb1cbdb6b8484315860e5aac1045c2e46193168b/README.rst.

However, I will point out that many of my personal use cases involve computations requiring environments that go beyond what is available in a standard build system like github actions or readthedocs. So, I think it is an advantage in some cases to be able to commit the output in an ipynb file, along with a corresponding https://github.com/mwouts/jupytext md file that does not contain the output, for inclusion of reasonably demanding computations in the html and pdf versions of the nbsphinx output without expecting the build server to be able to successfully execute all notebooks in their entirety.

A broader question would be: What example notebooks would be useful to have in an nbsphinx template repository? I just placed a couple I had on hand as an example for now, but would certainly be open to updating them to be more generally helpful to a wider audience. Perhaps a template repository for a documentation generation framework that is already self-documented is superfluous to most users.

mgeier commented 3 years ago

OK, using Github Actions and Github Pages is of course also good. I prefer RTD because of the multi-version hosting, but Github Pages is also fine for many cases.

many of my personal use cases involve computations requiring environments that go beyond what is available in a standard build system like github actions or readthedocs.

Sure, but I think this should not be the default case. I think users should be encouraged to commit notebook without outputs unless there is a reason to commit them.

What example notebooks would be useful to have in an nbsphinx template repository?

I think very basic (and short) examples should suffice, but they should probably use common libraries, e.g. Matplotlib.

There are already many places with general Jupyter example notebooks, a few links could be included for interested readers.

Perhaps a template repository for a documentation generation framework that is already self-documented is superfluous to most users.

I don't know, but I think a template repo doesn't hurt.

I personally have never used any template repo, but I think there are people out there who like that workflow.