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
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.
- contains all the configuration and settings information, and also allows for code executions.
- table of contents and typically a project description
- use to build, to spellcheck, to check links …
The Makefile is somewhat easier to use than the
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
Using Multiple Input Formats#
Sphinx by default uses
reStructuredText . Adding the formats your team uses, reduces barriers to documentation creation and maintenance.
MarkDown and other formats we edit the
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**!
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
Sphinx now parses
jupyter notebook parsing I chose
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
pip install myst-nb
Adding an extension reference to the
extensions = [ "myst_nb" ]
Add your notebook to a
toc directive in
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
sphinxcontrib-spelling which uses
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
extensions = [ ... "sphinxcontrib.spelling" ]
To change the default language add the following to
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
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
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
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.