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]

help

Show help for any command.

package-docs help [OPTIONS] [TOPIC]

Arguments

TOPIC

Optional argument