sphinx-last-updated-by-git

Project Homepage

https://pypi.org/project/sphinx-last-updated-by-git/

Project links

  • Homepage

  • Statistics

  • GitHub statistics:

  • Stars: 12

  • Forks: 2

  • Open issues/PRs: 2

Meta License: BSD License (BSD-2-Clause)

Author: Matthias Geier

Tags Sphinx, Git

Requires: Python >=3.6

Maintainers Avatar for Matthias.Geier from gravatar.com Matthias.Geier

Get the “last updated” time for each Sphinx page from Git

This is a little Sphinx extension that does exactly that. It also checks for included files and other dependencies and uses their “last updated” time if it’s more recent.

If a page doesn’t have a source file, its last_updated time is set to None.

The default value for html_last_updated_fmt is changed from None to the empty string.

Usage

  1. Install the Python package sphinx-last-updated-by-git

  2. Add 'sphinx_last_updated_by_git' to extensions in your conf.py

  3. Run Sphinx!

Options

  • If a source file is not tracked by Git (e.g. because it has been auto-generated on demand by autosummary_generate) but its dependencies are, the last_updated time is taken from them. If you don’t want this to happen, use git_untracked_check_dependencies = False.

  • If a source file is not tracked by Git, its HTML page doesn’t get a source link. If you do want those pages to have a sourcelink, set git_untracked_show_sourcelink = True. Of course, in this case html_copy_source and html_show_sourcelink must also be True, and the theme you are using must support source links in the first place.

  • By default, timestamps are displayed using the local time zone. You can specify a datetime.timezone object (or any tzinfo subclass instance) with the configuration option git_last_updated_timezone. You can also use any string recognized by babel, e.g. git_last_updated_timezone = 'NZ'.

  • By default, the “last updated” timestamp is added as an HTML <meta> tag. This can be disabled by setting the configuration option git_last_updated_metatags to False.

Caveats

  • When using a “Git shallow clone” (with the --depth option), the “last updated” commit for a long-unchanged file might not have been checked out. In this case, the last_updated time is set to None (and a warning is shown during the build).

    This might happen on https://readthedocs.org/ because they use shallow clones by default. The DONT_SHALLOW_CLONE feature flag should fix this.

    If you want to get rid of the warning, use this in your conf.py:

    suppress_warnings = ['git.too_shallow']

  • When a project on https://readthedocs.org/ using their default theme sphinx_rtd_theme was created before October 20th 2020, the date will not be displayed in the footer.

    One work-around is to enable the (undocumented) feature flag USE_SPHINX_LATEST.

    Another work-around is to override the defaults by means of a requirements.txt file containing something like this:

    sphinx>=2
sphinx_rtd_theme>=0.5

    See also issue #1.

License

BSD-2-Clause (same as Sphinx itself), for more information take a look at the LICENSE file.

Similar stuff
https://github.com/jdillard/sphinx-gitstamp
https://github.com/OddBloke/sphinx-git
https://github.com/MestreLion/git-tools (git-restore-mtime)
https://github.com/TYPO3-Documentation/sphinxcontrib-gitloginfo

Last change: Tue, 03 Aug 2021 10:25 PM UTC