Minimal working examples of Sphinx documentation

examples folder has four self-contained examples of sphinx-doc:

1. minimal: conf.py + index.rst + rtd theme
2. pages: toctree directive, more pages and markdown parser
3. pydata: pydata theme with two toctree levels
4. autodoc: create documentation from python docstrings

Your learning curve can be:

• conf.py + rtd theme + index.rst
• sphinx-build src dest, start dest/index.html
• toctree directive + more files
• myst parser for markdown
• pydata theme (optional)
• automodule directive for python documentation

Change to a specific directory of interest and run:

sphinx-build .  site
start site/index.html

Understanding sphinx

Before starting make sure you understand:

• source: markdown, restructured text (rst)
• output: html, pdf
• code docstrings
• source files (rst, markdown) -> theme -> config -> output (html, pdf)

Workflow:

• sphinx-build reads source files in rst or markdown format and renders html documentation from them using a provided theme and other configuration parameters
• sphinx uses own directives like .. toctree:: that allow more control over documention structure and content
• sphinx can also produce documentation in latex that build to PDF

Themes:

• read the docs is a popular theme for sphinx, but there are many others. pydata is a modern documentation theme for sphinx.

Directives:

• toctree directive is central to sphinx - it builds document tree for navigation
• autodoc is another directive that collects docstrings from code. This is how documentation is auto-generated.

conf.py:

• conf.py is a python script that is used by sphinx-build for configuration
• conf.py can be hand-written with just few lines or auto-generated with tons of options that are quite hard to understand

What may be difficult about sphinx

• sphinx consists of several sepearte command-line tools
• make scripts intended to help, but they also obfuscate what and how sphinx works
• configuration files and folder strucute autogenerated with sphinx-quickstart are a bit bloated
• there are many directives besides toctree and autodoc
• rst is harder than markdown, even though more powerful
• there is a search engine under same name as sphinx
• the word sphinx is difficult to rememder and type correctly

Docs and conf.py examples by project

Project	Source folder	conf.py
Hypermodern Packaging	docs	conf.py
IASA message_ix	docs	conf.py
pydata theme	docs	conf.py
librosa	docs	conf.py
cakephp	docs	conf.py

Read more

• minimalsphinx by Melissa Weber Mendonça

• nanotune (unofficial):

  • website
  • docs

Photo credits

Sphinx cat photos:

• Max Simonov, via Unsplash
• Simona Melegová, via Unsplash

Remaining questions

• sphinx-build -M latexpdf examples/pydata docs - what is M?
• sphinx-quickstart, sphinx-build, sphinx-apidoc, sphinx-autogen