リポジトリのコミット履歴を表示する sphinxcontrib-vcs を作りました

Sphinx で管理しているドキュメントの履歴や差分内容を気軽に確認できるようにするための Sphinx 拡張です。

Git と Mercurial に対応しています。Python 2/3 両対応ですが、Mercurial は Python 3 対応していないので Python 2.7 環境でしか動作しません。

以下 PyPI とそのドキュメントになります。

• https://pypi.python.org/pypi/sphinxcontrib-vcs/

  • ドキュメント: https://pythonhosted.org/sphinxcontrib-vcs/

経緯

類似の Sphinx 拡張として sphinx-git があります。当初は私もこの拡張機能を使っていました。私の用途として、差分内容を表示する機能を追加したかったのと sphinx-git のメンテナンスがあまり活発ではないのもあり、新規に自分で作り直すことにしました。sphinxcontrib-vcs は sphinx-git に影響を受けています。

インストール

$ pip install sphinxcontrib-vcs
$ vi conf.py
extensions = ['sphinxcontrib.vcs']

ディレクティブとオプション

..git:: または ..mercurial:: のディレクティブに以下のオプションを指定します。

• :number_of_revisions: 指定した件数のコミット履歴を表示する
• revision: revision: 指定したリビジョンのコミットログを表示する
• with_ref_url: 指定すると、コミットメッセージの下にリポジトリへのコミット URL を表示する (github/bitbucket のみ対応)
• include_diff: 指定すると、コミットメッセージの下に差分内容を表示する (初期状態は非表示にしており、コミットメッセージをクリックすると表示／非表示が切り替わる)

直近のコミット履歴を表示する

git のリポジトリだとこんな感じ。

指定したリビジョンのコミットログを表示する

こんな感じ。

まとめ

Sphinx そのものは数年前から使っていましたが、Sphinx 拡張を自分で作ってみたのは今回が初めてでした。実際に作ってみて Docutils と Sphinx の両方のドキュメントやソースを見ないといけないところがやや煩雑な印象を受けました。既に優れた拡張機能がたくさんあるのでそれらのソースを参考にしながら開発を進める方が早いような気がします。

以下に私が参考にしたサイトや情報などをまとめておきます。

拡張機能の開発のドキュメント

• The Docutils Document Tree
• Sphinx 公式ドキュメント - Sphinx拡張機能の開発
• (7日目) Sphinx 拡張を作ってみよう (sphinxcontrib.nicovideo)

Git/Mercurial のライブラリのドキュメント

• https://gitpython.readthedocs.io/en/stable/
  • よく出来ていて使いやすいものだと思います
• https://www.mercurial-scm.org/wiki/MercurialApi
  • Mercurial は API が公開されていないのでコマンドの実行結果をパースしています。いろんな環境でちゃんと動かないかも？

ソースのサンプルとして参考にした拡張機能

• https://bitbucket.org/birkenfeld/sphinx-contrib
  • ここに複数の拡張機能がまとまっているのでここから grep して参考にするのが良さそう
• https://github.com/OddBloke/sphinx-git
  • オリジナルの拡張機能、GitPython の使い方を調べました

Sphinx 拡張のテストツール

• https://github.com/sphinx-doc/sphinx-testing
  • @tk0miya さんのテストツール、こういうのあったんですね！