Sphinx: Setup#

I’m interested in building a useful documentation pipeline and will use it initially on these blog posts. I’m keen to have a complete working and tunable setup by the end of the week.

As always I’m working in a virtual environment.

First off, install sphinx

pip install -U sphinix

I then update my requirements.txt file using:

pip freeze > requirements.txt

As sphinx creates a lot of resource files, I create somewhere to put it all. I then run the quick-start.

mkdir docs
cd  docs
sphinx-quickstart .   # note the `period`

# to skip mkdir and cd we can
sphinx-quickstart docs # Caution: This option gave me
                       # permission errors on some attempts

Choose your name and your projects name. For the rest it’s easier to accept the defaults. All settings can be configured later if required.

The quick-start builds out the scaffolding structure for sphnix. There are three basic files to concern ourselves with.

  • conf.py
    • contains all the configuration and settings information, and also allows for code executions.
  • index.rst
    • table of contents and typically a project description
  • Makefile
    • use to build, to spellcheck, to check links …

The Makefile is somewhat easier to use than the sphinx build.

Building Docs#

To build the docs typically we use:

make clean  # gets rid of anything from before, a clean slate
make html   # builds all docs as html (other options exist)

Serve the Docs Locally#

To serve the docs locally use:

python3 -m http.server

The documentation is now accessible at http://localhost:8000/_build/html/index.html

Using Multiple Input Formats#

Sphinx by default uses reStructuredText . Adding the formats your team uses, reduces barriers to documentation creation and maintenance.

Markdown#

To use MarkDown and other formats we edit the conf.py file.

For markdown and reStructuredText only choose MySt-Parser. Full documentation can be found on the MySt website.

First install the module.

pip install myst-parser

Then edit the sphinx conf.py adding these lines.

extensions = ["myst_parser"]

As a test, I created helloworld.md with the following content.

# Hello, World
Punctuation **matters**!

Running the make html command now will give a warning that the file is not in any toc. To avoid this, edit the toctree directive in index.rst. Mine looks like this after the edit.

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

   helloworld.md

n Sphinx now parses reStructuredText and markdown files.

Jupyter Notebooks#

For jupyter notebook parsing I chose MySt-nb.

note: If you have the `MySt-parser` from the previous setion installed you should uninstall it. It conflicts with the `MySt-nb` . `MySt-nb`parses both `Markdown` and `Jupyter` notebooks.

Full documentation is available at the MyST NB website

Install

pip install myst-nb

Adding an extension reference to the conf.py .

extensions = [
	"myst_nb"
]

Add your notebook to a toc directive in index.rst.

Mine is now like this:

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

   helloworld.md
   Getting_to_Know_Sphinx.ipynb

If you get this error, WARNING: toctree contains reference to document DataWrangling that doesn't have a title: no link will be generated and don’t see your notebook in the navigation menu, then make the first cell in the notebook a markdown cell and choose a title. The title will be used in the menu/link generation.

Sphinx now parses reStructuredText, markdown and, jupter notebooks.

Spell Check#

I chose sphinxcontrib-spelling which uses pyEnchant.

Install on MacOS using brew and then pip. Complete instructions are available on the pyenchant website.

brew update
brew install enchant
pip install sphinxcontrib-spelling

Add the extension to conf.py .

extensions = [
	...
	"sphinxcontrib.spelling"
]

To change the default language add the following to conf.py.

spelling_lang="en_US"
tokenizer_lang="en_US"

en_US is the default. A full list of language codes are available on the ISO Standards website

To add words that are not in the standard dictionaries provided by pyEnchant use the following setting. This can be useful for brandnames, company lingo and the like. The file should contain one

spelling_word_list_filename="spelling_wordlist.txt"

Run the spelling test as part of the make command.

make spelling       # Spellcheck only
make html spelling  # Spellcheck and build (with any
                    # errors)

I introduced a spelling mistake in my helloworld.md and got the following useful output in the terminal.

helloworld.md:0: : Spell check: speling: This is a deliberate speling mistake..
Writing  /docs/_build/spelling/helloworld.spelling
writing output... [100%] index
WARNING: Found 1 misspelled words

I repeated using “davidjnevin”, got a spelling warning, added it to spelling_wordlist and received no errors. So that worked.

A full list of word filters output options are available on the sphinxcontrib.spelling website

It’s worth noting here that I use a spell check in my text editor. The sphinx spell check is as an additional check prior to building.

Link checking comes by default with sphinx

make linkcheck

Using this link https://www.davidjnevin.com I received the following error.

(      helloworld: line   22) redirect  https://www.davidjnevin.com - permanently to https://davidjnevin.com/
build succeeded.

Look for any errors in the above output or in _build/linkcheck/output.txt

Using this link https://davidjnevin.com/ I didn’t receive an error.

Sphinx is now up and running and usable. Next I’m exploring how to make it awesome.

#source

Carol Willing - Practical Sphinx - PyCon 2018