Sphinxで更新履歴ページを作成

Sphinx_Python_Documentation_Logo

Sphinx でドキュメント管理している時に、みんなどうやって更新履歴ページを作成しているのか気になったので、既存プロジェクトを調べてみた。

履歴管理方法

大きく分けて2通りあった。

  1. (主流)アプリケーションのChangeLog(や History や News)ファイルを Sphinx の更新履歴ページからインクルード
  2. (少数派)更新履歴ページにベタ書き

外部ファイルをインクルードしているプロジェクト

開発フローとしては、機能改修したら ChangeLog を更新すると、ドキュメントも連動する。

Sphinx

Sphinx 自体、この方法で履歴ページを管理している。

HTML : http://sphinx-doc.org/changes.html
元ファイル : http://sphinx-doc.org/_sources/changes.txt

CHANGES ファイルを引っ張っている

Python

HTML : http://docs.python.org/3.3/whatsnew/changelog.html
元ファイル : http://docs.python.org/3.3/_sources/whatsnew/changelog.txt

NEWS ファイルを引っ張っている

Tornado

HTML : http://www.tornadoweb.org/en/stable/releases.html
元ファイル : http://www.tornadoweb.org/en/stable/_sources/releases.txt

pylons

HTML : http://docs.pylonsproject.org/projects/pyramid/en/latest/changes.html
元ファイル : https://raw.github.com/Pylons/pyramid/1.4-branch/docs/changes.rst

pip

HTML : https://pip.readthedocs.org/en/latest/news.html
元ファイル : https://raw.github.com/pypa/pip/master/docs/news.rst

というように、Sphinx でドキュメント管理しており、履歴ページがあるプロジェクトは、アプリケーションの履歴ファイルを

更新履歴ページにベタ書きしているプロジェクト

SQLAlchemy

HTML : http://docs.sqlalchemy.org/en/latest/changelog/changelog_09.html
元ファイル : http://docs.sqlalchemy.org/en/latest/_sources/changelog/changelog_09.txt

昔は CHANGES ファイルに更新履歴を書いていたけれども、sphinx を更新するようにフローを変えた
2重管理はしていない

なお、元ファイルは BTS から https://pypi.python.org/pypi/changelog/ を使って自動生成している模様。

boto

HTML : http://boto.cloudhackers.com/en/latest/releasenotes/v2.23.0.html
元ファイル : http://boto.cloudhackers.com/en/latest/_sources/releasenotes/v2.23.0.txt

アプリの履歴ファイルはなく、sphinx で一元管理。
昔からなのかは不明

結論 : 今回はファイルインクルード形式にした。

Advertisements
Tagged with:
Posted in project

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Archives
%d bloggers like this: