Ideas on how to switch HTML generation to nbsphinx

[jlstevens]

Since nbsite was created, the idea of building notebooks into webpages has caught on with various projects tackling the idea. In particular, nbsphinx probably has a better maintained core functionality than nbsite.

The suggestion would be to generate HTML from notebooks using nbsphinx, pushing that tool as far as we can with ad hoc processing of HTML files for any other other bits we need afterwards. Discussing this with @ceball, we had the following ideas:

1. Separating the conda environment running nbsite from the notebook execution environment

   Assuming nbsphinx follows the usual Jupyter conventions, there are two possible ways of doing this that we know of:

   1. Install nb_conda_kernels to make conda environments available as Jupyter kernels.
   2. Or activate the target environment and run something like python -m ipykernel install /path/to/jupyter_config to make it available as a kernel.

   Then in the sphinx config, you can set the custom kernel name.

2. Pre-executing code (e.g loading extensions) with nbsphinx_execute_arguments

   One thing nbsite does is support for code execution before the notebook cells are run (e.g to preload a holoviews extension). This should be possible with nbsphinx using the nbsphinx_execute_arguments config.

3. Adding special headers or footers.

   We want to have ''Download this notebook/project here' links at the top/bottom of the build HTML pages. This looks like it should be possible with nbsphinx which supports jinja2 templates for prologs/epilogs. You can see how Dask does it in their conf.py.

We would still need to do holoviz specific handling of many things e.g gallery generation, thumbnail generation, link munging, interaction with GitHub/CI etc etc. The question then is whether it is worth the effort to switch to a 3rd party (presumably better maintained!) tool for the HTML generation side of things. The main benefit I see would be that you could get to an 80% (or 90%) solution of building some sort of webpages without needing to think about nbsite: any bugs would be reported to nbsphinx and out of our hands!

[philippjfr]

We have now switched to myst_nb to do the parsing and rendering. Many of the items here are still relevant but in general we are moving away from building notebooks and are instead moving towards Markdown + Pyodide based documentation so I'm not sure we really need a lot of this.