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 the pipelines_lsst_io repository 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_io for 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:

  1. Removes any existing symlinks in the modules, packages, and _static directories.

  2. Finds packages set up by EUPS that have Sphinx-enabled doc/ directories and links their module and package directories into the pipelines_lsst_io repository. The doc/manifest.yaml file in each package is what defines the package and module documentation directories for each package.

  3. Run a single, monolithic Sphinx build on the pipelines_lsst_io repository 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.geom or package (afw) name to exclude from the documentation. Provide multiple -s options to skip multiple names.

--enable-doxygen-conf, --disable-doxygen-conf

Toggle creating a Doxygen configuration.

--enable-doxygen, --disable-doxygen

Toggle running a Doxygen build.

Toggle symlinking package documentation directories (disable for debugging only).

--enable-sphinx, --disable-sphinx

Toggle running a Sphinx build.

--use-doxygen-conf-in, --use-doxygen-conf

Use doxygen.conf.in files in packages rather than the sconsUtils-generated doxygen.conf files.

--doxygen-conf <doxygen_conf_defaults_path>

Path to a Doxygen configuration file that provides defaults. This file is referenced by the finalized Doxygen configuration with the @INCLUDE_PATH tag. Defaults to a doxygen configuration built into Documenteer.

--dox <dox>

Run Doxygen on only the packages explicitly listed, rather than automatically discovering set up packages.

--skip-dox <skip_dox>

Skip running Doxygen on these packages.

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)

  • _doxygen (the Doxygen build)

stack-docs clean [OPTIONS]

help

Show help for any command.

stack-docs help [OPTIONS] [TOPIC]

Arguments

TOPIC

Optional argument

listcc

List C++ API names available in the Doxygen tag file for cross-linking.

To make a cross-link from a reStructuredText file or Python docstring, use the syntax:

:lsstcc:`{{name}}`

Example usage:

stack-docs listcc -t class -t function -p lsst::afw::table

stack-docs listcc [OPTIONS]

Options

-t, --type <api_types>

Type of documentation to list. Omit to list all API types. Provide multiple arguments to list several API types. “class” includes both classes and their methods.

Options:

namespace | struct | class | file | define | group | variable | typedef | enumeration | function

-p, --pattern <pattern>

Regular expression pattern to filter API names.

--escape, --no-escape

Escape the name so it can be used in reStructuredText (default).