riddle of the sphinx-quickstart

rob mahurin

2026-01-19 09:44

I have been reminding myself about Sphinx, a content management system for static file trees which is most commonly used for Python documentation. I keep repeating the same changes to the default setup. Here is a summary.

I do like the built-in sphinx-quickstart which populates a conf.py for you. But I don't like some of the choices it makes. I'm sure there are ways to customize what it does, which is the right long-term solution for my personal distaste. But for right now, I have notes here.

Running sphinx-quickstart will create a Makefile (and a make.bat which I guess is for victims of inferior operating systems) in the current directory. That's dumb and gross if you are using any kind of organization that keeps your top-level directory clean, or if you have your own Makefile there. I think the right solution is
```
cd /path/to/my/project
mkdir sphinx && pushd sphinx
sphinx-quickstart # do stuff here
echo build >> .gitignore
```
However, if sphinx isn't building documentation for modules in the current directory, it can't load them. So you have to open of conf.py in an editor and add, near the top,
```
import pathlib, sys
sys.path.append(pathlib.Path('..').resolve())
```

While you're there, add the "extensions" that give you the basic functionality of automatic documentation:

extensions = [
    ...,
    'sphinx.ext.autodoc',    # Extract documentation from docstrings
    'sphinx.ext.mathjax',    # I guess not everybody needs math? Weird.
    'sphinx.ext.viewcode',   # Each documentation snippet should link to code
]

I also like to have (as ordinary variables in conf.py) these configuration options:
```
autoclass_content = 'both'
autodoc_member_order = 'bysource'
```
With this, your .rst files can just have some combination of
```
.. automodule:: module_name
.. autoclass:: module_name.ClassName
   :members:
```
and the documentation will basically appear, typeset from .rst-language docstrings, in your HTML output, without having to do very much in your .rst source files at all.
I also like to install sphinx-autobuild, and add a default Makefile target like:
```
autobuild:
    $(MAKE) -C . dirhtml \
        SPHINXBUILD=sphinx-autobuild \
        SPHINXOPTS="--port 8008 --watch .."
```
Dear future-me who is cutting and pasting: don't forget that Makefiles want command lines to be indented with tabs rather than spaces.