documenteer.ext#

documenteer.ext.bibtex Module#

Support for Rubin BibTeX files for pybtex/sphinxcontrib.bibtex.

Functions#

setup(app)

Add this plugin to the Sphinx application.

documenteer.ext.githubbibcache Module#

A Sphinx extension that caches BibTeX files from GitHub repositories.

These bibfiles can be used with sphinxcontrib-bibtex’s bibliography directive.

Functions#

setup(app)

Set up the documenteer.ext.autocppapi Sphinx extensions.

documenteer.ext.jira Module#

Rubin JIRA ticket reference roles.

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

Functions#

setup(app)

Set up the Jira ticket reference roles.

documenteer.ext.lastmodified Module#

Sphinx extension that adds a “Last updated” timestamp to each page based on the page’s Git commit history.

For each HTML output page, this extension computes the most recent commit datetime across the page’s source file and any files that the page pulls in via include/literalinclude directives.

That datetime is exposed to the page template in three forms:

  • last_updated – the date formatted with documenteer_last_modified_date_format in the commit’s timezone offset. Sphinx emits this as the docbuild:last-update meta tag, and it is the value any theme-agnostic last-updated rendering uses.

  • documenteer_last_modified_iso – the canonical UTC ISO 8601 timestamp (for example 2024-06-01T00:00:00+00:00).

  • documenteer_last_modified_date – the UTC date as YYYY-MM-DD (for example 2024-06-01).

Documenteer’s user-guide preset overrides pydata-sphinx-theme’s last-updated component (src/documenteer/templates/pydata/ last-updated.html) to render “This page was last modified on <date>.” as a <time> element. Its datetime attribute carries documenteer_last_modified_iso and its visible text is documenteer_last_modified_date (the UTC YYYY-MM-DD fallback); rubin-last-modified.js rewrites that text to the reader’s local date.

The same datetime is also emitted into the page <head> as machine-readable metadata – article:modified_time (Open Graph), dcterms.modified (Dublin Core), and a Schema.org dateModified (JSON-LD) – so that this extension is the single source of truth for the page’s last-modified date.

Using Git commit dates (rather than filesystem modification times) means the timestamps are meaningful in CI builds, where checkouts have arbitrary mtimes.

Important

The date is derived from the Git history, so CI checkouts must fetch the full history. With actions/checkout set fetch-depth: 0; a shallow clone makes every page report the same (wrong) date.

Functions#

setup(app)

Set up the documenteer.ext.lastmodified Sphinx extension.

Classes#

LastModified()

Computes per-page "last modified" timestamps from Git commit history.

documenteer.ext.lsstdocushare Module#

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

Functions#

setup(app)

Set up the LSST DocuShare and ls.st reference roles.

documenteer.ext.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#

setup(app)

Set up the mock code reference roles.

documenteer.ext.openapi Module#

A Sphinx extension for generating the OpenAPI Spec for a FastAPI application.

Functions#

setup(app)

Set up the OpenAPI extension.

documenteer.ext.remotecodeblock Module#

remote-code-block directive that works like literalinclude, but supports getting content over https.

Functions#

setup(app)

Set up the remote-code-block directive.

documenteer.ext.robots Module#

Sphinx extension for automatically generating robots.txt files.

This extension automatically creates and inserts a robots.txt file into the built HTML site if no such robots.txt file already exists and if a sitemap.xml file does exist in the built site. In the generated robots.txt file, it links to the sitemap using the Sphinx html_baseurl configuration value.

Functions#

generate_robots_txt(app, exception)

Generate a robots.txt file automatically if conditions are met.

setup(app)

Set up the robots extension.

This page was last modified on .