stack-docs command-line app¶
Use the stack-docs command-line app to compile the full https://pipelines.lsst.io site from the https://github.com/lsst/pipelines_lsst_io 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 pipelines.lsst.io site locally (DM Developer Guide)
stack-docs¶
stack-docs is a CLI for building LSST Stack documentation, such as pipelines.lsst.io.
This command should be run on the “main” documentation repository, namely https://github.com/lsst/pipelines_lsst_io.
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 pipelines.lsst.io site from thepipelines_lsst_iorepository 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 https://documenteer.lsst.io.
stack-docs [OPTIONS] COMMAND [ARGS]...
Options
-
-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_iofor example) or a subdirectory of it.
-
-v,--verbose¶ Enable verbose output (debug-level logging).
-
--version¶ Show the version and exit.
build¶
Build documentation as HTML.
This command performs these steps:
- Removes any existing symlinks in the
modules,packages, and_staticdirectories. - Finds packages set up by EUPS that have Sphinx-enabled doc/ directories
and links their module and package directories into the
pipelines_lsst_iorepository. Thedoc/manifest.yamlfile in each package is what defines the package and module documentation directories for each package. - Run a single, monolithic Sphinx build on the
pipelines_lsst_iorepository 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 documenteer.stackdocs.build
APIs.
stack-docs build [OPTIONS]
Options
-
-s,--skip<skip>¶ A module (e.g.
lsst.afw.geomor package (afw) name to exclude from the documentation. Provide multiple -s options to skip multiple names.
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
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]