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 https://pipelines.lsst.io site builds, use the stack-docs app instead.
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
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]