<!--
.. title: riddle of the sphinx-quickstart
.. slug: riddle-of-the-sphinx-quickstart
.. date: 2026-01-19 09:44:17 UTC-06:00
.. tags: sphinx, python, tools
.. category: computing
.. link:
.. description: In which I save myself some hassle later by modifying sphinx-quickstart.
.. type: text
-->

I have been reminding myself about
[Sphinx](https://pypi.org/project/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.

<!-- TEASER_END -->

I do like the built-in [`sphinx-quickstart`][1] 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.

[1]: https://www.sphinx-doc.org/en/master/man/sphinx-quickstart.html

 1. 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

 2. 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())

 3. 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
        ]

 4. 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.

 5. I also like to install [`sphinx-autobuild`][2], 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.

[2]: https://pypi.org/project/sphinx-autobuild/