An introduction to Sphinx

Credit: this notebook draws heavily on Carol Willing’s Practical Sphinx tutorial, originally MIT licensed. All modifications made here are also MIT licensed.

Sphinx?

The Python documentation generator.

By default, Sphinx assumes input files are created using the reStructuredText format (this quick reference can be handy). But Sphinx is an extensible system, and with a couple of custom extensions, we can:

This is what the class website uses!

The Jupyter Docs

Available at jupyter.readthedocs.io:

Getting Started

If you didn’t already, in your class environment, run:

conda install sphinx
conda install -c conda-forge nbsphinx recommonmark ghp-import

Create project folder

mkdir my-doc-project
cd my-doc-project

Run sphinx’s quickstart

We can leave most items as default:

sphinx-quickstart

Build docs from your docs root directory

Type make for help on all the possible targets. Typical workflow:

make clean
make html
make linkcheck

To view the docs

open _build/html/index.html

Or start a webserver and view

python -m http.server

Configuration

conf.py

  • Use for configuration settings.
  • This is a Python file.
  • You can execute Python code for custom builds.

conf.py

  • themes
  • source files
  • extensions

Themes in conf.py

Easiest Use the default.

Easy Use another standard theme.

Customize css, js and override templates (jinja2)

Create your own theme Only do if the above doesn’t meet your needs.

Source files

More than .rst

  • reStructuredText .rst and sometimes .txt
  • markdown .md
  • Jupyter notebooks .ipynb

conf.py

reStructuredText .rst

No changes needed in conf.py.

conf.py (cont.)

Markdown .md using recommonmark.

# For conversion from markdown to html
import recommonmark.Parser

# Add a source file parser for markdown
source_parsers = {
    '.md': 'recommonmark.parser.CommonMarkParser',
}

# Add type of source files
source_suffix = ['.rst', '.md']

conf.py (cont.)

Jupyter notebooks .ipynb using nbsphinx extension.

extensions = [
    'sphinx.ext.mathjax',
    'nbsphinx',  # This lets us use notebooks
]

# I execute the notebooks manually in advance. If notebooks test the code,
# they should be run at build time.
nbsphinx_execute = 'never'
nbsphinx_allow_errors = True

# Add type of source files
source_suffix = ['.rst', '.md', '.ipynb']

index.rst

Table of Contents using each source file type

.. toctree::
   :maxdepth: 2
   :caption: Sphinx Tips

   installation
   configuration.md
   content.ipynb
   deploy-on-rtd

Github Pages

  • Host static websites (HTML+JS) directly from a Github Repo!
  • https://pages.github.com
  • All we need to have is a branch called gh-pages that has an HTML build (with an index.html file at the start). Github does the rest!

Using Github Pages to post a sphinx site easily

Make sure you answer yes to the question about Github Pages in the quickstart! If you didn’t, add to your extensions list:

'sphinx.ext.githubpages'

Add this target to the Makefile. It automates pushing to GitHub Pages:

.PHONY: github

github: html
    ghp-import $(BUILDDIR)/html/
    git push -u origin gh-pages
    @echo
    @echo "Published to Github"

Let’s post our site

  • Turn our little test into a git repo (git init, etc...)
  • Go to GitHub and create a GH repo for it
  • Type:
ghp-import _build/html/
git push -u origin gh-pages
  • Go to Settings page and see that Github Pages is enabled.

Once we verify the above works, we can just use, thanks to our above target:

make github

Love your docs!