Recipes

Jupyter Notebooks

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 .ipynb file directly, note the labels_),

    "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