The nbsphinx extension is capable of rendering notebooks, nicely! A few things to keep in mind though.
The toplevel heading is the document title to Sphinx - same as with Sphinx’s own reST documents. Give one toplevel heading at the beginning, all others one deeper.
Do not use trailing underscores in notebook text. For example, this test (taken from an
.ipynbfile directly, note the
"source": [ "#### Use the result: output-properties\n", "* labels_: cluster membership for each point in the input sequence\n", ]
brings a warning,
/home/jfasch/work/jfasch-home/courses/records/2019-11-12/code/BigPlan.ipynb:686: WARNING: Unknown target name: "labels".
Running Sphinx From Source¶
$ export PYTHONPATH=$HOME/work/sphinx:$PYTHONPATH $ python ~/work/sphinx/sphinx/cmd/build.py -W --keep-going --no-color ~/work/jfasch-home /tmp/jfasch-home/html