LastModified#

class documenteer.ext.lastmodified.LastModified#

Bases: object

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

A single instance is created in setup, which connects two html-page-context handlers:

  • add_time_context (early, before pydata-sphinx-theme’s update_and_remove_templates) exposes the UTC <time> context variables. pydata empty-checks the last-updated footer component and drops it unless these variables already exist when it runs, so they must be set first.

  • add_last_modified (late, after sphinx-last-updated-by-git’s own handler) sets the human-readable last_updated value and appends the machine-readable <head> metadata.

Both handlers share a single per-page Git computation via get_last_modified_datetime, which is memoized in _date_cache.

The instance lazily constructs a GitRepository on first use and remembers when timestamps can’t be produced, so that those builds are a clean no-op. Timestamps are disabled when the source directory isn’t a Git repository (including the pytest temporary source directory) and when the repository is a shallow clone (whose truncated history would yield misleading dates – a warning is emitted in that case).

Methods Summary

add_last_modified(app, pagename, ...)

Populate the last_updated value and <head> metadata.

add_time_context(app, pagename, ...)

Expose the UTC <time> context variables for the footer.

get_last_modified_datetime(app, pagename)

Compute the most recent Git commit datetime for a page.

Methods Documentation

add_last_modified(app, pagename, templatename, context, doctree)#

Populate the last_updated value and <head> metadata.

This html-page-context handler runs late – after sphinx-last-updated-by-git’s own handler (which the user-guide preset auto-loads through sphinx-sitemap and which resets last_updated to None when html_last_updated_fmt is unset) and after pydata-sphinx-theme’s _fix_canonical_url (so the JSON-LD metadata sees the corrected pageurl). It sets the last_updated context value – formatted in the commit’s own timezone offset and emitted by pydata-sphinx-theme as the docbuild:last-update meta tag – and appends machine-readable last-modified metadata to the page <head>.

The <time> footer context variables are set separately and earlier by add_time_context.

Parameters:

  • app (Sphinx) – The Sphinx application.

  • pagename (str) – The docname of the page being rendered.

  • templatename (str) – The template used to render the page.

  • context (dict) – The template context, modified in place.

  • doctree (object | None) – The doctree for the page, or None for pages without a source document (such pages are skipped).

Return type:

None

add_time_context(app, pagename, templatename, context, doctree)#

Expose the UTC <time> context variables for the footer.

This html-page-context handler runs early – before pydata-sphinx-theme’s update_and_remove_templates (priority 500), which empty-checks the last-updated footer component and drops it unless its context is already populated. Documenteer’s override of that component renders a <time> element gated on documenteer_last_modified_iso, so this handler must set it first:

  • documenteer_last_modified_iso – the canonical UTC ISO 8601 timestamp, used in the <time datetime="..."> attribute (which rubin-last-modified.js localizes to the reader’s timezone).

  • documenteer_last_modified_date – the UTC date as YYYY-MM-DD, the no-JavaScript visible fallback text.

Parameters:

  • app (Sphinx) – The Sphinx application.

  • pagename (str) – The docname of the page being rendered.

  • templatename (str) – The template used to render the page.

  • context (dict) – The template context, modified in place.

  • doctree (object | None) – The doctree for the page, or None for pages without a source document (such pages are skipped).

Return type:

None

get_last_modified_datetime(app, pagename)#

Compute the most recent Git commit datetime for a page.

Parameters:

  • app (Sphinx) – The Sphinx application.

  • pagename (str) – The docname of the page being rendered.

Returns:

The timezone-aware datetime of the most recent commit touching the page’s own source file or any of its include/literalinclude dependencies, or None if there’s no Git repository or none of those files are tracked.

Return type:

datetime.datetime or None