Simplest way to run Sphinx on one python file

Question

We have a Sphinx configuration that'll generate a slew of HTML documents for our whole codebase. Sometimes, I'm working on one file and I just would like to see the HTML output from that file to make sure I got the syntax right without running the whole suite.

I looked for the simplest command I could run in a terminal to run sphinx on this one file and I'm sure the info's out there but I didn't see it.

Answer 1

Sphinx processes reST files (not Python files directly). Those files may contain references to Python modules (when you use autodoc). My experience is that if only a single Python module has been modified since the last complete output build, Sphinx does not regenerate everything; only the reST file that "pulls in" that particular Python module is processed. There is a message saying updating environment: 0 added, 1 changed, 0 removed.

To explicitly process a single reST file, specify it as an argument to sphinx-build:

sphinx-build -b html -d _build/doctrees . _build/html your_filename.rst 

Answer 2

This is done in two steps:

1. Generate rst file from the python module with sphinx-apidoc.
2. Generate html from rst file with sphinx-build.

This script does the work. Call it while standing in the same directory as the module and provide it with the file name of the module:

#!/bin/bash
# Generate html documentation for a single python module

PACKAGE=${PWD##*/}
MODULE="$1"
MODULE_NAME=${MODULE%.py}

mkdir -p .tmpdocs
rm -rf .tmpdocs/*
sphinx-apidoc \
    -f -e --module-first --no-toc -o .tmpdocs "$PWD" \
    # Exclude all directories
    $(find "$PWD" -maxdepth 1 -mindepth 1 -type d) \
    # Exclude all other modules (apidoc crashes if __init__.py is excluded)
    $(find "$PWD" -maxdepth 1 -regextype posix-egrep \
        ! -regex ".*/$MODULE|.*/__init__.py" -type f)
rm .tmpdocs/$PACKAGE.rst
# build crashes if index.rst does not exist
touch .tmpdocs/index.rst
sphinx-build -b html -c /path/to/your/conf.py/ \
    -d .tmpdocs .tmpdocs .tmpdocs .tmpdocs/*.rst

echo "**** HTML-documentation for $MODULE is available in .tmpdocs/$PACKAGE.$MODULE_NAME.html"