Python API reference

documenteer.sphinxconfig.stackconf Module

Sphinx configuration defaults for LSST Stack packages.

Notes

Some configurations based on astropy-helpers https://github.com/astropy/astropy-helpers/blob/master/astropy_helpers/sphinx/conf.py see licenses/astropy-helpers.txt

Functions

build_package_configs(project_name[, ...])	Builds a dict of Sphinx configurations useful for the doc/conf.py files of individual LSST Stack packages.
build_pipelines_lsst_io_configs(*, project_name)	Build a dict of Sphinx configurations that populate the conf.py of the main pipelines_lsst_io Sphinx project for LSST Science Pipelines documentation.

documenteer.sphinxconfig.technoteconf Module

Sphinx configuration bootstrapping for LSST Technical Notes.

Functions

configure_technote(meta_stream)

Builds a dict of Sphinx configuration variables given a central configuration for LSST Design Documents and a metadata YAML file.

documenteer.sphinxconfig.utils Module

Utilities for sphinx configuration.

Functions

form_ltd_edition_name([git_ref_name])	Form the LSST the Docs edition name for this branch, using the same logic as LTD Keeper does for transforming branch names into edition names.
get_filepaths_with_extension(extname[, root_dir])	Get relative filepaths of files in a directory, and sub-directories, with the given extension.
get_project_content_commit_date([root_dir, ...])	Get the datetime for the most recent commit to a project that affected Sphinx content.
read_git_branch()	Obtain the current branch name from the Git repository.
read_git_commit_timestamp([repo_path])	Obtain the timestamp from the current head commit of a Git repository.
read_git_commit_timestamp_for_file(filepath)	Obtain the timestamp for the most recent commit to a given file in a Git repository.

documenteer.sphinxext Package

Sphinx/docutils extensions for LSST DM documentation.

Enable these extension by adding documenteer.sphinxext to your extensions list in conf.py:

extensions = [
   # ...
   'documenteer.sphinxext'
]

Some extensions require project-specific dependencies and are not automatically enabled. They should be specified individually. They are:

• documenteer.sphinxext.bibtex

Functions

setup(app)

Wrapper for the setup functions of each extension module.

documenteer.sphinxext.bibtex Module

Extensions to support LSST bibliographies with sphinxcontrib-bibtex.

Functions

setup(app)

Add this plugin to the Sphinx application.

Classes

LsstBibtexStyle([label_style, name_style, ...])

Bibtex style that understands docushare fields in LSST bibliographies.

documenteer.sphinxext.jira Module

JIRA ticket reference roles (for stories, epics, RFCs, etc.).

This module is heavily influenced by sphinx-issue (Steven Loria). See /licenses/sphinx-issue.txt for licensing information.

Functions

jira_bracket_role(name, rawtext, text, ...)	Sphinx role for referencing a JIRA ticket with ticket numbers enclosed in braces.
jira_parens_role(name, rawtext, text, ...[, ...])	Sphinx role for referencing a JIRA ticket with ticket numbers enclosed in parentheses.
jira_role(name, rawtext, text, lineno, inliner)	Sphinx role for referencing a JIRA ticket.
setup(app)

documenteer.sphinxext.lsstdocushare Module

LSST LSST the Docs and DocuShare/ls.st reference roles.

Functions

lsst_doc_shortlink_role(name, rawtext, text, ...)	Link to LSST documents given their handle using LSST's ls.st link shortener.
lsst_doc_shortlink_titlecase_display_role(...)	Link to LSST documents given their handle using LSST's ls.st link shortener with the document handle displayed in title case.
lsstio_doc_shortlink_role(name, rawtext, ...)	Link to LSST documents given their handle that are hosted on lsst.io (Rubin's deployment of LSST the Docs).
setup(app)	param app:

documenteer.sphinxext.mockcoderefs Module

Sphinx extensions to mock Python code reference roles.

These roles are useful for temporarily adding semantically-markedup APIs while waiting for the API reference itself to be added.

Functions

mock_code_ref_role(name, rawtext, text, ...)
setup(app)

documenteer.sphinxext.packagetoctree Module

Sphinx extensions for creating toctrees for packages and modules for the Pipelines documentation.

Functions

setup(app)

Classes

ModuleTocTree(name, arguments, options, ...)	Toctree that automatically displays a list of modules in the Stack documentation.
PackageTocTree(name, arguments, options, ...)	Toctree that automatically lists packages in the Stack documentation.

documenteer.stackdocs.build Module

Stack documentation build system.

Functions

build_stack_docs(root_project_dir[, ...])

Build stack Sphinx documentation (main entrypoint).

documenteer.stackdocs.doxygen Module

Configuration and execution of Doxygen at the stack level.

Functions

preprocess_package_doxygen_conf(*, conf, package)	Preprocess a Doxygen configuration for an individual package that is based on a package's doxygen.conf.in file.
render_doxygen_mainpage()	Render the mainpage.dox page that provides content for the Doxygen subsite's homepage.
get_doxygen_default_conf_path()	Get the path to the doxygen configuration file included with Documenteer.
get_cpp_reference_tagfile_path()	Get the path to the Doxygen tag file for cppreference.com that's included with Documenteer.
run_doxygen(*, conf, root_dir)	Run Doxygen.

Classes

DoxygenConfiguration([include_paths, ...])

A restricted Doxygen configuration.

documenteer.stackdocs.packagecli Module

Implements the package-docs CLI for single-package documentation builds in the LSST Stack.

documenteer.stackdocs.pkgdiscovery Module

Utilities for discovering packages in a stack and discovering attributes and their documentation.

Functions

discover_setup_packages([scope])	Summarize packages currently set up by EUPS, listing their set up directories and EUPS version names.
find_table_file(root_project_dir)	Find the EUPS table file for a project.
list_packages_in_eups_table(table_text)	List the names of packages that are required by an EUPS table file.
find_package_docs(package_dir[, skipped_names])	Find documentation directories in a package using manifest.yaml and heuristics.

Classes

Package(root_dir, doc_dir[, package_dirs, ...])	Metadata about a stack package's documentation content.
NoPackageDocs	Exception raised when documentation is not found for an EUPS package.

documenteer.stackdocs.rootdiscovery Module

Utilities for detecting the root directory of Sphinx documentation.

Functions

discover_package_doc_dir(initial_dir)	Discover the doc/ dir of a package given an initial directory.
discover_conf_py_directory(initial_dir)	Discover the directory containing the conf.py file.

documenteer.stackdocs.stackcli Module

Implements the stack-docs CLI for stack documentation builds.

documenteer.requestsutils Module

Utilities for working with requests.

Functions

requests_retry_session([retries, ...])

Create a requests session that handles errors by retrying.

documenteer.sphinxrunner Module

Run Sphinx directly through its Python API.

Functions

run_sphinx(root_dir[, job_count, ...])

Run the Sphinx build process.