🤖

sphinx-last-updated-by-git: Gitから取得した最終更新日時を表示する

2021/07/23に公開

概要

phinx-last-updated-by-gitを使って、sphinxで生成したページに、最終更新日時を表示する方法を紹介します。

phinx-last-updated-by-gitは、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.

最終更新日時を表示することにより、読み手は「このドキュメントは全然更新されていないから、情報が間違っているかもしれない」などを判断することができます。

環境

  • Python 3.8.6
  • sphinx 4.1.1
  • pydata-sphinx-theme 0.6.3
  • phinx-last-updated-by-git 0.3.0

前提条件

sphinxのテーマはpydata-sphinx-themeを利用しています。以下の理由から、pydata-sphinx-themeを採用しています。

  • 利用できるテーマの中で、一番古臭なくない印象を受けた
  • 最終更新日時を表示するテンプレートlast-updated.htmlが用意されている。

sphinxの設定ファイルは以下の通りです。

docs/conf.py
project = 'test'
copyright = '2021, yuji38kwmt'
author = 'yuji38kwmt'

extensions = [
]
templates_path = ['_templates']
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
html_theme = 'pydata_sphinx_theme'
html_static_path = ['_static']

手順

公式サイトには以下のように手順が記載されていますが、具体的な方法が分からなかったので、記事にまとめました。

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!

インストール

PyPIからパッケージをインストールします。

$ pip install sphinx-last-updated-by-git

conf.pyの設定

extensionsにsphinx_last_updated_by_gitを追加します。

docs/conf.py
extensions = ['sphinx_last_updated_by_git'
]

pydata-sphinx-themeのデフォルト設定では、最終更新日時が表示されるテンプレートを使用していないので、この状態でsphinxを実行しても最終更新日時は表示されません。

pydata_sphinx_themeには最終更新日時を表示するためのテンプレートが、最初から用意されています。このテンプレートをfooterに追加します。
https://pydata-sphinx-theme.readthedocs.io/en/latest/user_guide/sections.html#a-list-of-built-in-templates-you-can-insert-into-sections

docs/conf.py
html_theme_options = {
  "footer_items": ["copyright", "sphinx-version", "last-updated"],
}

なお、last-updatedの中身は、以下の通りです。グローバル変数last_updatedが最終更新日時に展開されます。

pydata_sphinx_theme/_templates/last-updated.html
<p class="last-updated">
{% trans last_updated=last_updated|e %}Last updated on {{ last_updated }}.{% endtrans %}<br>
</p>

sphinx-buildの実行

sphinx-buildを実行すると、フッターにGitから取得した最終更新日時が表示されます。

Last updated on Jul 23, 2021.

ReadTheDocsにデプロイされたドキュメントでも、Gitから取得した最終更新日時が表示されます。

補足

日時フォーマットの変更

日時フォーマットを変更する場合は、html_last_updated_fmtに日付フォーマットを設定します。

たとえば、時間も表示するために以下の日時フォーマットを設定します。

docs/conf.py
html_last_updated_fmt = '%Y-%m-%d %H:%M:%S'

ビルドした結果、フッターには以下の値が表示されます。

Last updated on 2021-07-23 12:31:29.

phinx-last-updated-by-gitを使わない場合

phinx-last-updated-by-gitを使わなくても最終更新日時は表示できますが、その場合最終更新日は「ビルドされた日時」になります。
https://www.sphinx-doc.org/ja/master/templating.html#last_updated

GitHubで編集を提案

Discussion