stack-docs command-line app

Use the stack-docs command-line app to compile the full site from the repository. For single-package doc builds, use the To preview the documentation for a single package during development, use the package-docs app instead.

See also

Building the site locally (DM Developer Guide)


stack-docs is a CLI for building LSST Stack documentation, such as

This command should be run on the “main” documentation repository, namely

The stack-docs command replaces the usual Makefile and sphinx-build system for Sphinx projects. This dedicated tool provide subcommands that are engineered specifically for building the pipelines_lsst_io project.

The key commands provided by stack-docs are:

  • stack-docs build: compile the site from the pipelines_lsst_io repository and linked packages.
  • stack-docs clean: removes build products. Use this command to clear the build cache.

See also: package-docs, a tool for building previews of package documentation.

For more information about stack-docs, see

stack-docs [OPTIONS] COMMAND [ARGS]...


-d, --dir <root_project_dir>

Root Sphinx project directory. You don’t need to set this argument explicitly as long as the current working directory is the main documentation repo (pipelines_lsst_io for example) or a subdirectory of it.

-v, --verbose

Enable verbose output (debug-level logging).


Show the version and exit.


Build documentation as HTML.

This command performs these steps:

  1. Removes any existing symlinks in the modules, packages, and _static directories.
  2. Finds packages set up by EUPS that have Sphinx-enabled doc/ directories and links their module and package directories into the pipelines_lsst_io repository. The doc/manifest.yaml file in each package is what defines the package and module documentation directories for each package.
  3. Run a single, monolithic Sphinx build on the pipelines_lsst_io repository and linked packages.

By default, the build site is located in the _build/html directory of the pipelines_lsst_io repository.

To peek inside the build process, see the APIs.

stack-docs build [OPTIONS]


-s, --skip <skip>

A module (e.g. lsst.afw.geom or package (afw) name to exclude from the documentation. Provide multiple -s options to skip multiple names.


Clean Sphinx build products.

Use this command to clean out build products after a failed build, or in preparation for running a build from a clean state.

This command removes the following directories from the pipelines_lsst_io directory:

  • _build (the Sphinx build itself)
  • modules (symlinks to the module doc directories of Stack packages)
  • packages (symlinks to the package doc directories of Stack packages)
  • py-api (pages created by automodapi for the Python API reference)
stack-docs clean [OPTIONS]


Show help for any command.

stack-docs help [OPTIONS] [TOPIC]



Optional argument