Building Sphinx documentation with setuptools
python setup.py --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:
[build_sphinx] 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!
Filed under: technical |
Tags: distutils, documentation, python, setuptools, sphinx