sphinx-build

Build documentation

$ sphinx-build [[-b|--builder]] [html|epub|text|latex|man|...] [path/to/source_dir] [path/to/build_dir]

$ sphinx-build [[-b|--builder]] [html] [path/to/docs_dir] [path/to/build_dir]

sphinx-build -b buildername [OPTIONS] sourcedir outputdir [filenames...]
sphinx-build -M buildername [OPTIONS] sourcedir outputdir

-b buildername
    Selects the builder to use for generating the output. Common builders include html, latex, man, epub, and text.

-M buildername
    Activates 'master' builder mode. This is often used by generated Makefiles and typically implies a cleaner build environment.

-a
    Forces a full rebuild of all documents, even if they appear up-to-date. Useful for ensuring consistency.

-E
    Don't use a saved environment, forcing re-reading of all source files and rebuilding internal structures. Similar to -a but specifically targets the environment.

-n
    Activates 'nitpicky' mode. In this mode, Sphinx will warn about all missing references (e.g., to classes, functions, or external documentation) that it can't resolve.

-q
    Suppresses output for standard messages, only showing warnings and errors.

-Q
    Suppresses all output, including warnings and errors. Useful for automated scripts where only the exit code matters.

-v
    Increases verbosity. Can be specified multiple times (e.g., -vvv) for more detailed output, including debug information.

-w file
    Writes all warnings and errors to the specified file instead of standard error.

-W
    Turns all warnings into errors. The build process will exit with a non-zero status code if any warnings occur, preventing an incomplete or problematic build.

-T
    Show full traceback on exceptions. Useful for debugging crashes within Sphinx itself or its extensions.

-c confdir
    Specifies an alternative directory for the conf.py configuration file. By default, Sphinx looks for conf.py in the sourcedir.

-D setting=value
    Overrides a configuration setting defined in conf.py with the specified value. Can be used multiple times.

-t tag
    Defines a tag. Conditional content marked with .. only:: <tag> directives will only be included if the tag is defined. Can be used multiple times.

-j N
    Runs the build in parallel with N jobs. 'auto' uses the number of CPU cores. Improves build time for large projects on multi-core systems.

sourcedir
    The path to the directory containing the project's source documentation files (e.g., .rst or .md files) and typically the conf.py configuration file.

outputdir
    The path to the directory where the generated documentation will be placed. This directory will be created if it does not exist.

[filenames...]
    Optional. A list of specific source file paths (relative to sourcedir) to rebuild. If omitted, all modified files (or all files with -a or -E) are built.

The sphinx-build command is the primary command-line utility for generating documentation using the Sphinx documentation generator.
It processes source files, typically written in reStructuredText or MyST (Markdown), and converts them into various output formats, known as 'builders'. Common output formats include HTML (static websites), LaTeX (for PDF generation), man pages, and EPUB ebooks.
sphinx-build manages the entire build process: parsing source files, resolving cross-references, applying themes, indexing content, and managing the build environment to ensure efficient incremental builds.
It is widely used in the Python ecosystem and beyond for project documentation, books, and articles, offering powerful features like extensibility through extensions, internationalization, and a clean separation of content and presentation.

Requires a conf.py configuration file, typically located in the sourcedir, to define project-specific settings and extensions.
Build performance can vary significantly based on project size, number of extensions, and chosen builder.
The outputdir should not be the same as the sourcedir to avoid conflicts and accidental deletion of source files during cleanup operations.

Sphinx uses 'builders' to convert the parsed document tree into various output formats. Each builder is specialized for a particular output type. Common builders include html (for static web pages), latex (which can then be compiled to PDF), man (for Unix manual pages), epub (for e-readers), and text (for plain text output). You select a builder using the -b option.

The conf.py file is the central configuration file for a Sphinx project. It's a Python script where you define project metadata (e.g., project name, author), enable extensions, specify themes, and customize various build behaviors. sphinx-build reads this file to understand how to process and build your documentation.

Sphinx maintains a 'build environment' in the .doctrees directory (or specified by -d) within your outputdir. This environment caches parsed document trees and metadata, allowing Sphinx to perform incremental builds very quickly by only processing files that have changed since the last build. The -E option can be used to explicitly discard this cached environment.

Sphinx was created by Georg Brandl in 2008, initially to build the official Python documentation. Its ease of use, extensibility, and high-quality output quickly led to its adoption by a wider community for general project documentation. It popularized the use of reStructuredText for technical documentation and later introduced support for MyST (Markdown), further expanding its reach. Its development is community-driven and continues to evolve as a cornerstone of technical documentation.

sphinx-quickstart(1), make(1), rst2html(1), python(1)