Sphinxish

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