package-docs command-line app#

Use the package-docs command-line app to compile the documentation for a single Stack package. This is useful for local previewing during development, though links to other packages will be broken. For full site builds, use the stack-docs app instead.

See also

Building single-package documentation locally (DM Developer Guide)


package-docs is a CLI for building single-package previews of documentation in the LSST Stack.

Use package-docs during development to quickly preview your documentation and docstrings.


Using package-docs to compile standalone documentation for a single package will generate warnings related to missing references. This is normal because the full documentation set is not built in the mode. Before shipping revised documentation for a package, always make sure cross-package references work by doing a full-site build either locally with the stack-docs CLI or the site’s Jenkins job.

The key commands provided by package-docs are:

  • package-docs build: compile the package’s documentation.

  • package-docs clean: removes documentation build products from a package.

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


-d, --dir <root_dir>#

Root Sphinx doc/ directory. You don’t need to set this argument explicitly as long as the current working directory is any of:

  • the root of the package

  • the doc/ directory

  • a subdirectory of doc/

-v, --verbose#

Enable verbose output (debug-level logging).


Show the version and exit.


Build documentation as HTML.

The build HTML site is located in the doc/_build/html directory of the package.

package-docs build [OPTIONS]


-W, --warning-is-error#

Treat warnings as errors.

-n, --nitpicky#

Activate Sphinx’s nitpicky mode.


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 package’s doc/ directory:

  • _build (the Sphinx build itself)

  • py-api (pages created by automodapi for the Python API reference)

package-docs clean [OPTIONS]


Show help for any command.

package-docs help [OPTIONS] [TOPIC]



Optional argument