Documenteer

Sphinx extensions, configurations, and tooling for LSST Data Management documentation projects.

Documenteer is developed on GitHub at https://github.com/lsst-sqre/documenteer.

Python API reference

documenteer.sphinxconfig.stackconf Module

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

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

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

Functions

setup(app)

Wrapper for the setup functions of each individual extension module.

documenteer.sphinxext.bibtex Module

Functions

setup(app)

Add this plugin to the Sphinx application.

documenteer.sphinxext.jira Module

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

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

Functions

mock_code_ref_role(name, rawtext, text, …)

setup(app)

documenteer.sphinxext.packagetoctree Module

Functions

setup(app)

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.

run_doxygen(*, conf, root_dir)

Run Doxygen.

Classes

DoxygenConfiguration([inputs, excludes, …])

A restricted Doxygen configuration.

Class Inheritance Diagram

digraph inheritance9378903a35 { rankdir=LR; size="8.0, 12.0"; "DoxygenConfiguration" [URL="api/documenteer.stackdocs.doxygen.DoxygenConfiguration.html#documenteer.stackdocs.doxygen.DoxygenConfiguration",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5)",target="_top",tooltip="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.

Class Inheritance Diagram

digraph inheritance91459828b0 { rankdir=LR; size="8.0, 12.0"; "NoPackageDocs" [URL="api/documenteer.stackdocs.pkgdiscovery.NoPackageDocs.html#documenteer.stackdocs.pkgdiscovery.NoPackageDocs",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5)",target="_top",tooltip="Exception raised when documentation is not found for an EUPS package."]; "Package" [URL="api/documenteer.stackdocs.pkgdiscovery.Package.html#documenteer.stackdocs.pkgdiscovery.Package",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5)",target="_top",tooltip="Metadata about a stack package's documentation content."]; }

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

Functions

requests_retry_session([retries, …])

Create a requests session that handles errors by retrying.

documenteer.sphinxrunner Module

Functions

run_sphinx(root_dir)

Run the Sphinx build process.