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.
For each file, the "author date" of the Git commit where it was last changed
is taken to be its "last updated" time. Uncommitted changes are ignored.
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
#. Install the Python package ``sphinx-last-updated-by-git``
#. Add ``'sphinx_last_updated_by_git'`` to ``extensions`` in your ``conf.py``
#. 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 = 'Pacific/Auckland'``.
* 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``.
* Files can be excluded from the last updated date calculation by passing
a list of exclusion patterns to the configuration option
``git_exclude_patterns``.
These patterns are checked on both source files and dependencies
and are treated the same way as Sphinx's exclude_patterns_.
* Individual commits can be excluded from the last updated date
calculation by passing a list of commit hashes to the configuration
option ``git_exclude_commits``.
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.
To avoid this problem, you can edit your config file ``.readthedocs.yml``:
.. code:: yaml
version: 2
build:
os: "ubuntu-22.04"
tools:
python: "3"
jobs:
post_checkout:
- git fetch --unshallow || true
For more details, `read the docs`__.
__ https://docs.readthedocs.io/en/latest/build-customization.html#unshallow-git-clone
This might also happen when using Github Actions,
because `actions/checkout`__ also uses shallow clones by default.
This can be changed by using ``fetch-depth: 0``:
.. code:: yaml
steps:
- uses: actions/checkout@v3
with:
fetch-depth: 0
__ https://github.com/actions/checkout
If you only want to get rid of the warning (without actually fixing the problem),
use this in your ``conf.py``::
suppress_warnings = ['git.too_shallow']
* If depedency file does not exist, a warning is being emitted.
If you only want to get rid of the warning (without actually fixing the problem),
use this in your ``conf.py``::
suppress_warnings = ['git.dependency_not_found']
* 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`_.
* In Sphinx versions 5.0 and 5.1, there has been
a regression in how dependencies are determined.
This could lead to spurious dependencies
which means that some "last changed" dates were wrong.
This has been fixed in Sphinx version 5.2 and above.
See also `issue #40`_.
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
.. _Sphinx: https://www.sphinx-doc.org/
.. _last_updated: https://www.sphinx-doc.org/en/master/
templating.html#last_updated
.. _exclude_patterns: https://www.sphinx-doc.org/en/master/usage/
configuration.html#confval-exclude_patterns
.. _autosummary_generate: https://www.sphinx-doc.org/en/master/
usage/extensions/autosummary.html#confval-autosummary_generate
.. _html_copy_source: https://www.sphinx-doc.org/en/master/
usage/configuration.html#confval-html_copy_source
.. _html_show_sourcelink: https://www.sphinx-doc.org/en/master/
usage/configuration.html#confval-html_show_sourcelink
.. _html_last_updated_fmt: https://www.sphinx-doc.org/en/master/
usage/configuration.html#confval-html_last_updated_fmt
.. _datetime.timezone: https://docs.python.org/3/library/
datetime.html#timezone-objects
.. _babel: https://babel.pocoo.org/
.. _feature flag: https://docs.readthedocs.io/en/latest/
guides/feature-flags.html
.. _issue #1: https://github.com/mgeier/sphinx-last-updated-by-git/issues/1
.. _issue #40: https://github.com/mgeier/sphinx-last-updated-by-git/issues/40
Raw data
{
"_id": null,
"home_page": "https://github.com/mgeier/sphinx-last-updated-by-git/",
"name": "sphinx-last-updated-by-git",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "Sphinx, Git",
"author": "Matthias Geier",
"author_email": "Matthias.Geier@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/03/fd/de1685b6dab173dff31da24e0d3b29f02873fc24a1cdbb7678721ddc8581/sphinx_last_updated_by_git-0.3.8.tar.gz",
"platform": "any",
"description": "Get the \"last updated\" time for each Sphinx page from Git\n=========================================================\n\nThis is a little Sphinx_ extension that does exactly that.\nIt also checks for included files and other dependencies and\nuses their \"last updated\" time if it's more recent.\nFor each file, the \"author date\" of the Git commit where it was last changed\nis taken to be its \"last updated\" time. Uncommitted changes are ignored.\n\nIf a page doesn't have a source file, its last_updated_ time is set to ``None``.\n\nThe default value for html_last_updated_fmt_ is changed\nfrom ``None`` to the empty string.\n\nUsage\n #. Install the Python package ``sphinx-last-updated-by-git``\n #. Add ``'sphinx_last_updated_by_git'`` to ``extensions`` in your ``conf.py``\n #. Run Sphinx!\n\nOptions\n * If a source file is not tracked by Git (e.g. because it has been\n auto-generated on demand by autosummary_generate_) but its dependencies\n are, the last_updated_ time is taken from them. If you don't want this\n to happen, use ``git_untracked_check_dependencies = False``.\n\n * If a source file is not tracked by Git, its HTML page doesn't get a\n source link. If you do want those pages to have a sourcelink, set\n ``git_untracked_show_sourcelink = True``. Of course, in this case\n html_copy_source_ and html_show_sourcelink_ must also be ``True``, and\n the theme you are using must support source links in the first place.\n\n * By default, timestamps are displayed using the local time zone.\n You can specify a datetime.timezone_ object (or any ``tzinfo`` subclass\n instance) with the configuration option ``git_last_updated_timezone``.\n You can also use any string recognized by babel_,\n e.g. ``git_last_updated_timezone = 'Pacific/Auckland'``.\n\n * By default, the \"last updated\" timestamp is added as an HTML ``<meta>``\n tag. This can be disabled by setting the configuration option\n ``git_last_updated_metatags`` to ``False``.\n\n * Files can be excluded from the last updated date calculation by passing\n a list of exclusion patterns to the configuration option\n ``git_exclude_patterns``.\n These patterns are checked on both source files and dependencies\n and are treated the same way as Sphinx's exclude_patterns_.\n\n * Individual commits can be excluded from the last updated date\n calculation by passing a list of commit hashes to the configuration\n option ``git_exclude_commits``.\n\nCaveats\n * When using a \"Git shallow clone\" (with the ``--depth`` option),\n the \"last updated\" commit for a long-unchanged file\n might not have been checked out.\n In this case, the last_updated_ time is set to ``None``\n (and a warning is shown during the build).\n\n This might happen on https://readthedocs.org/\n because they use shallow clones by default.\n To avoid this problem, you can edit your config file ``.readthedocs.yml``:\n\n .. code:: yaml\n\n version: 2\n build:\n os: \"ubuntu-22.04\"\n tools:\n python: \"3\"\n jobs:\n post_checkout:\n - git fetch --unshallow || true\n\n For more details, `read the docs`__.\n\n __ https://docs.readthedocs.io/en/latest/build-customization.html#unshallow-git-clone\n\n This might also happen when using Github Actions,\n because `actions/checkout`__ also uses shallow clones by default.\n This can be changed by using ``fetch-depth: 0``:\n\n .. code:: yaml\n\n steps:\n - uses: actions/checkout@v3\n with:\n fetch-depth: 0\n\n __ https://github.com/actions/checkout\n\n If you only want to get rid of the warning (without actually fixing the problem),\n use this in your ``conf.py``::\n\n suppress_warnings = ['git.too_shallow']\n\n * If depedency file does not exist, a warning is being emitted.\n\n If you only want to get rid of the warning (without actually fixing the problem),\n use this in your ``conf.py``::\n\n suppress_warnings = ['git.dependency_not_found']\n\n * When a project on https://readthedocs.org/ using their default theme\n ``sphinx_rtd_theme`` was created before October 20th 2020,\n the date will not be displayed in the footer.\n\n One work-around is to enable the (undocumented) `feature flag`_\n ``USE_SPHINX_LATEST``.\n\n Another work-around is to override the defaults\n by means of a ``requirements.txt`` file containing something like this::\n\n sphinx>=2\n sphinx_rtd_theme>=0.5\n\n See also `issue #1`_.\n\n * In Sphinx versions 5.0 and 5.1, there has been\n a regression in how dependencies are determined.\n This could lead to spurious dependencies\n which means that some \"last changed\" dates were wrong.\n This has been fixed in Sphinx version 5.2 and above.\n\n See also `issue #40`_.\n\nLicense\n BSD-2-Clause (same as Sphinx itself),\n for more information take a look at the ``LICENSE`` file.\n\nSimilar stuff\n | https://github.com/jdillard/sphinx-gitstamp\n | https://github.com/OddBloke/sphinx-git\n | https://github.com/MestreLion/git-tools (``git-restore-mtime``)\n | https://github.com/TYPO3-Documentation/sphinxcontrib-gitloginfo\n\n.. _Sphinx: https://www.sphinx-doc.org/\n.. _last_updated: https://www.sphinx-doc.org/en/master/\n templating.html#last_updated\n.. _exclude_patterns: https://www.sphinx-doc.org/en/master/usage/\n configuration.html#confval-exclude_patterns\n.. _autosummary_generate: https://www.sphinx-doc.org/en/master/\n usage/extensions/autosummary.html#confval-autosummary_generate\n.. _html_copy_source: https://www.sphinx-doc.org/en/master/\n usage/configuration.html#confval-html_copy_source\n.. _html_show_sourcelink: https://www.sphinx-doc.org/en/master/\n usage/configuration.html#confval-html_show_sourcelink\n.. _html_last_updated_fmt: https://www.sphinx-doc.org/en/master/\n usage/configuration.html#confval-html_last_updated_fmt\n.. _datetime.timezone: https://docs.python.org/3/library/\n datetime.html#timezone-objects\n.. _babel: https://babel.pocoo.org/\n.. _feature flag: https://docs.readthedocs.io/en/latest/\n guides/feature-flags.html\n.. _issue #1: https://github.com/mgeier/sphinx-last-updated-by-git/issues/1\n.. _issue #40: https://github.com/mgeier/sphinx-last-updated-by-git/issues/40\n",
"bugtrack_url": null,
"license": "BSD-2-Clause",
"summary": "Get the \"last updated\" time for each Sphinx page from Git",
"version": "0.3.8",
"project_urls": {
"Homepage": "https://github.com/mgeier/sphinx-last-updated-by-git/"
},
"split_keywords": [
"sphinx",
" git"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e1fbe496f16fa11fbe2dbdd0b5e306ede153dfed050aae4766fc89d500720dc7",
"md5": "78ec32b2e4f266dcb0419e3d2b060818",
"sha256": "6382c8285ac1f222483a58569b78c0371af5e55f7fbf9c01e5e8a72d6fdfa499"
},
"downloads": -1,
"filename": "sphinx_last_updated_by_git-0.3.8-py3-none-any.whl",
"has_sig": false,
"md5_digest": "78ec32b2e4f266dcb0419e3d2b060818",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 8580,
"upload_time": "2024-08-11T07:15:53",
"upload_time_iso_8601": "2024-08-11T07:15:53.244461Z",
"url": "https://files.pythonhosted.org/packages/e1/fb/e496f16fa11fbe2dbdd0b5e306ede153dfed050aae4766fc89d500720dc7/sphinx_last_updated_by_git-0.3.8-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "03fdde1685b6dab173dff31da24e0d3b29f02873fc24a1cdbb7678721ddc8581",
"md5": "41ec27aafeb3f5dbb68d5e2be0ea8e9c",
"sha256": "c145011f4609d841805b69a9300099fc02fed8f5bb9e5bcef77d97aea97b7761"
},
"downloads": -1,
"filename": "sphinx_last_updated_by_git-0.3.8.tar.gz",
"has_sig": false,
"md5_digest": "41ec27aafeb3f5dbb68d5e2be0ea8e9c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 10785,
"upload_time": "2024-08-11T07:15:54",
"upload_time_iso_8601": "2024-08-11T07:15:54.601652Z",
"url": "https://files.pythonhosted.org/packages/03/fd/de1685b6dab173dff31da24e0d3b29f02873fc24a1cdbb7678721ddc8581/sphinx_last_updated_by_git-0.3.8.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-11 07:15:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mgeier",
"github_project": "sphinx-last-updated-by-git",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "sphinx-last-updated-by-git"
}
JSON
