Documenteer

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

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

• Change Log

Pipelines projects

• Installing Documenteer for pipelines.lsst.io
• Overview of the pipelines.lsst.io build system
• stack-docs command-line app
• package-docs command-line app

Sphinx extensions

• Sphinx extensions for the LSST Science Pipelines task framework

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