sphinx-last-updated-by-git: Gitから取得した最終更新日時を表示する
概要
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の設定ファイルは以下の通りです。
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
- Install the Python package sphinx-last-updated-by-git
- Add 'sphinx_last_updated_by_git' to extensions in your conf.py
- Run Sphinx!
インストール
PyPIからパッケージをインストールします。
$ pip install sphinx-last-updated-by-git
conf.pyの設定
extensionsにsphinx_last_updated_by_gitを追加します。
extensions = ['sphinx_last_updated_by_git'
]
pydata-sphinx-themeのデフォルト設定では、最終更新日時が表示されるテンプレートを使用していないので、この状態でsphinxを実行しても最終更新日時は表示されません。
pydata_sphinx_themeには最終更新日時を表示するためのテンプレートが、最初から用意されています。このテンプレートをfooterに追加します。
html_theme_options = {
"footer_items": ["copyright", "sphinx-version", "last-updated"],
}
なお、last-updatedの中身は、以下の通りです。グローバル変数last_updatedが最終更新日時に展開されます。
<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に日付フォーマットを設定します。
たとえば、時間も表示するために以下の日時フォーマットを設定します。
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を使わなくても最終更新日時は表示できますが、その場合最終更新日は「ビルドされた日時」になります。
Discussion