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 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.
setup(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.