Working with Sphinx

Set Up Sphinx for Note Taking

Install Sphinx: pip install -U Sphinx

In Anacdona Python: conda install -c anaconda sphinx

Create a folder for notes and switch to it: mkdir intro_data_sci_notes

Run Sphinx quicstart from the notes directory: sphinx-quickstart

Press <Enter> to accept all the defaults EXCEPT the following:

Enter y: > Separate source and build directories (y/n) [n]: y

Enter project name, author name and release number when prompted:

> Project name: Intro to Data Science Notes
> Author name(s): Rob Fowler
> Project release []: 1.0

I said y to a Makefile and n to Windows command file since I’m using Linux:

A Makefile and a Windows command file can be generated for you so that you
only have to run e.g. `make html' instead of invoking sphinx-build
> Create Makefile? (y/n) [y]: y
> Create Windows command file? (y/n) [y]: n

Quickstart is now complete. The intro_data_sci_notes folder now contains folders named build and source along with the Makefile.

The source folder is where my notes will go. Sphinx created a master document, index.rst which will serve as the home page for my notes. There is also a Python file, which contains lots of options for controlling how Sphinx works. I make one change to this file, on line 77, which reads:

html_theme = 'alabaster'

I change this to:

html_theme = 'classic'

because I am a fan of the original Sphinx theme, which includes my favorite color (blue).

index.rst includes these items:

Welcome to Intro to Data Science Notes's documentation!

.. toctree::
   :maxdepth: 2
   :caption: Contents:

Indices and tables

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

I edit it to get rid of the Indices and tables section which I do not need for this project. I change the title to Notes on Introduction to Data Science with Python.

The toctree section is a special bit of Sphinx magic that generates a table of contents from the notes in source.. The table’s headings and subheadings are grabbed from the titles of the documents and the headers within each document. Here is an example of a hierarchy of headings in ReStructuredText:

Heading 1

Heading 2

Heading 3

Heading 4

Note the maxdepth option, which determines how many sublevels of headings will be shown. For my Sphinx projects, I like to have all the project’s documents, headings and subheadings included in a master, nested table of contents on the first page, so I remove the maxdepth entirely.

Create HTML

In main Sphinx dir: make html