sphinx-build -b html: Build Sphinx Docs in CI
sphinx-build -b html SOURCEDIR OUTDIR compiles reStructuredText and Markdown sources into a static HTML site.
sphinx-build is the core Sphinx command. The builder (-b) picks the output format; in CI you almost always want html plus -W so a broken cross-reference fails the job.
What it does
sphinx-build reads conf.py from the source directory, processes every document, and writes the chosen output. -b html is the default builder for a browsable site; other builders include linkcheck, latexpdf, and dirhtml. Positional args are SOURCEDIR then OUTDIR.
Common usage
sphinx-build -b html docs docs/_build/html
# fail the build on any warning (recommended in CI)
sphinx-build -b html -W --keep-going docs docs/_build/html
# check for broken external links
sphinx-build -b linkcheck docs docs/_build/linkcheckOptions
| Flag | What it does |
|---|---|
| -b <builder> | Builder to run: html, dirhtml, linkcheck, latexpdf |
| -W | Turn warnings into errors (non-zero exit) |
| --keep-going | With -W, report all warnings instead of stopping at the first |
| -n | Nitpicky mode: warn on every missing reference |
| -a | Write all files, not just changed ones |
| -E | Do not use a saved environment, rebuild from scratch |
| -j auto | Parallelize across CPUs |
| -q / -Q | Quiet / very quiet output |
In CI
Use -W --keep-going so warnings fail the pipeline but you still see all of them in one run. Add -n to catch missing cross-references. Cache docs/_build/.doctrees between runs to speed incremental builds; pass -E when you need a guaranteed clean rebuild.
Common errors in CI
Warning, treated as error: followed by a message (for example document isn't included in any toctree) is the classic -W failure; fix the underlying warning or remove -W. Could not import extension <name> (exception: No module named ...) means a Sphinx extension is not installed in the runner. Theme error: no theme named '...' found means the HTML theme package is missing from requirements.