question about an html TOC

I guess this is neither a bug report nor a feature request (although on second thought...), but a simple question about best practices

I am writing a course; like many others I have split it into, say, one notebook per chapter; the original notebooks are RISE-enabled slideshows

I'd like to publish some handouts; static html is fine, and I like your output with the 'toggle code' and 'toggle outputs' buttons; but I'm not sure how to make an index that looks like a TOC ?

is this something that ipypublish can help with ? I've looked a bit into the sphinx extensions but that sounds truly overkill, unless I missed something obvious ?

regardless, thanks for the awesome tool !

following-up

I think I'm doing something quite wrong; my workflow so far is (I'm still exploring my options here)

use nbconvert to execute the notebooks once and for good and store those in a subdir
in order to get a all-in-one html output, I use nbtb cat to produce a concatenated ALL.ipynb of these executed notebooks
at that point, I can produce a single ALL.html that is fine but has no TOC
I can also use this as the entry point to nbpublish -f sphinx_ipypublish_main.run

funny thing is that processing that takes ages; and I see mentions of the individual notebooks being enumerated while processing, which is odd because the only entry point that I give to ipypublish is ALL.ipynb; so it definitely feels like the directory is scanned somehow

I feel like I'm missing something so obvious that I can't see it, is that right ?

Hey @parmentelat, sorry for the late response! I wanted to finish some relevant updates first, which took a bit longer than expected. So in v0.10.7 you can now use code/output toggling with Sphinx, as you can see in the documentation here and here.

I would strongly recommend using Sphinx for HTML output, rather than the html_ipypublish_ converters. At this point I'd say they are almost deprecated, since all their functionality can be replicated in Sphinx, and its just a more complete solution.

One of the benefits of Sphinx is that you don't have to merge all your notebooks first. By default, Sphinx treats all the files in the folder, with extensions it recognizes as part of the documentation (i.e. .rst and .ipynb with the ipypublish.sphinx.notebook extension). That is why it is processing all the individual notebooks.

Once you get the hang of it, its dead simple to use Sphinx: just create a conf.py and index.rst (you can look at the ones auto-generated by sphinx_ipypublish_main.run for a basic outline or use sphinx-quickstart) and create a ToC in the index.rst with all the notebooks (and rst files) you want in the documentation, and finally run sphinx-build (which you can also run via a Makefile).

Heres another project where I use a bunch of static .ipynb + .rst to create my documentation: https://aiida-crystal17.readthedocs.io/en/develop/user_guide/calc_main.html

Hope that helps, let me know if you have any more problems :)

hello

thanks for the feedback; I do have further questions though :)

first off, because all this is still a little obscure to me (see 2nd question), I tried to upgrade (I have ipypublish==0.10.8) and keep my workflow unchanged; that is to say, create a ALL.ipynb and run

nbpublish -f sphinx_ipypublish_main.run -o /Users/tparment/git/flotpython-primer/notebooks/exporting exporting/ALL.ipynb

right now this gives me a html output with no code cell at all and no toggle button either

second, all your examples directly call sphinx-build, and so I fail to see where ipypublish actually comes into play in the case of the linked Makefile; also my Makefile has explicit rules and calls to nbconvert to generate the 'executed' version of my notebooks, that are otherwise nbstripout'ed before I send them to git, and it feels like your workflow manages this phase much more elegantly

so I'd love to clean up my workflow but am currently a bit puzzled as to how to achieve this

Hey thanks, yeh its good to get a perspective from someone who is new to sphinx.

It's creating a document, so that's a good sign!
sphinx_ipypublish_main.run by default ignores code cells, use sphinx_ipypublish_all.run instead
the toggle functions are optional extras, that can be controlled in the document level metadata. To turn them on for a specific notebook, merge this into your notebook file:

    "metadata": {
        "ipub": {
            "sphinx": {
                "toggle_input": true,
                "toggle_output": true,
                "toggle_input_all": true,
                "toggle_output_all": true
            }
        }
    }

So as explained here: https://ipypublish.readthedocs.io/en/latest/sphinx_ext_notebook.html#usage,
sphinx-build calls the conf.py file. If the extension ipypublish.sphinx.notebook is specified, this calls this function:

ipypublish/ipypublish/sphinx/notebook/extension.py

Line 20 in 8f6627b

def setup(app):

which "tells" Sphinx that it knows how to convert files with extension .ipynb (and .Rmd), so any time sphinx comes across one of these files, it defers the conversion to ipypublish.

As an example in the conf.py for my other package: conf.py#L65, I load ipypublish.sphinx.notebook, and specify some control options for ipypublish, including to use the sphinx_ipypublish_all.ext.noexec export configuration.

hey

just to report that I've gotten this to work just fine, that's awesome

eventually I have decided against having execution and doc creation done in a single pass, this is because the sphinx pass runs on readthedocs and the notebooks run a bash kernel, and do rather aggressive git scenarios, I was not comfortable with the single pass approach

so I have added the exec'ed version of my notebooks to the git repo for rtd, which is suboptimal but managable; next time that I have a pure python project I'll try to have both passes done under sphinx

otherwise, I have one very minor issue to report, which is that notebooks that have e.g. toggle_input_all set to true but no code cell end up with this

instead of the expected

I know, I just need to turn that off but for now this is automated in my environment;
I would still argue that, either it shows up nicely and does nothing, or it does not show up at all :)

again this is totally minor, thanks for the great tool !

I'm closing this one as I've got everything running super smooth on my end

thanks !