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.
See also
Building single-package documentation locally (DM Developer Guide)
package-docs¶
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.
Warning
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]...
Options
-
-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).
-
--version¶ Show the version and exit.
build¶
Build documentation as HTML.
The build HTML site is located in the doc/_build/html directory
of the package.
package-docs build [OPTIONS]
clean¶
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]