「最近更新したページ一覧」を生成するsphinx拡張、recentpages ( #sphinxjp アドベントカレンダー 13日目)

雑記

アドベントカレンダーへの参加を大幅に遅刻しました。すいません。

この記事では、私が今年作成した「最近更新したページ一覧」を生成するsphinx拡張、sphinxcontrib-recentpages を紹介します。

sphinxcontrib-recentpages とは？

Sphinx プロジェクト内で作成した rst ファイルを更新された順にソートしてリスト表示するための Sphinx 拡張です。

この拡張を使えば、pukiwiki に標準で備わっている「最近更新されたページ」を表示することができます。

プロジェクトページはこちら: https://bitbucket.org/shiumachi/sphinxcontrib-recentpages

インストール方法

easy_install でインストールしてください。

$ easy_install sphinxcontrib-recentpages

その後、sphinx プロジェクトの conf.py に以下を追加してください。

extensions += ['sphinxcontrib.recentpages']

使い方

ディレクティブとサイドバー表示の2種類があります。

ディレクティブ表示

下記のように書けば、最近更新された直近 num 件を表示します。

.. recentpages::
:num: 3

サイドバー表示

conf.py に以下を追加してください。

# サイドバー表示を有効にします
recentpages_sidebar = True

# サイドバーの設定に recentpages.html を追加します。
html_sidebars = {'**': ['localtoc.html', 'relations.html', 'sourcelink.html', 'searchbox.html', 'recentpages.html']}

# サイドバーに表示するページの件数です。デフォルトは5件です。省略可
recentpages_sidebar_pages = 5

既知のバグ・制限事項・今後の予定

  • 現在ファイルの更新日でしか更新時刻を取得していないので、git リポジトリで sphinx を管理している場合、git clone すると更新時刻が正しく表示されません。今後 git のコミットログを元に更新日を判断できるような機能を追加する予定です。
  • mercurial にもそのうち対応する(かもしれません)
  • 導入すると、make html 以外を実行できなくなります。make html 以外を実行するときだけ conf.py を編集するか、別にプロジェクトページを立ててください。いずれ修正します。