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
  • RT @__apf__: How to write a research paper: a guide for software engineers & practitioners. docs.google.com/presentation/d… /cc @inwyrd 6 months ago
  • RT @HayatoChiba: 昔、自然と対話しながら数学に打ち込んだら何かを悟れるのではと思いたち、専門書1つだけ持ってパワースポットで名高い奈良の山奥に1週間籠ったことがある。しかし泊まった民宿にドカベンが全巻揃っていたため、水島新司と対話しただけで1週間過ぎた。 それ… 6 months ago
  • RT @googlecloud: Ever wonder what underwater fiber optic internet cables look like? Look no further than this deep dive w/ @NatAndLo: https… 6 months ago
  • @ijin UTC+01:00 な時間帯で生活しています、、、 1 year ago
  • RT @mattcutts: Google's world-class Site Reliability Engineering team wrote a new book: amazon.com/Site-Reliabili… It's about managing produc… 1 year ago
%d bloggers like this: