Building Sphinx documentation with setuptools


Starting with Sphinx version 0.5, you can now control and launch your documentation builds from within the warm fuzzy world of setuptools!


python --help-commands

inside your setuptools project, and if you see a build_sphinx target in the “Extra commands” section, you’re in luck.

The Sphinx build can be configured from your setup.cfg in the same directory. Here are the available options (taken from here):

fresh-env: Discard saved environment
all-files: Build all files
source-dir: Source directory
build-dir: Build directory
builder: The builder to use. Defaults to “html”

For reference, here’s the relevant part of setup.cfg from one of our projects:

source-dir = docs/source
build-dir  = docs/build
all_files  = 1

Note the lack of quotes around the directories – I found that including quotes confused the command.

For large bodies of code, configuration can become fragmented and messy extremely quickly unless you’re very careful; little features like this can really help centralise your configuration, and keep you sane. Pre-requisites, source/binary distributions, unit-tests, documentation and distribution to PyPI all configured through one tool? Yes please!


%d bloggers like this: