まとめ

本章では次のようなことを、どのように行うのかについて、具体的に説明してきました:

• 効果的に文章を書くための、いくつかのルールの使用方法

• PythonistaのLaTeXとも言うべき、reStructuredTextの使用方法

• ドキュメントのポートフォリオとランドスケープの構築

• すばらしいWebのドキュメントを生成することができる、Sphinxの使用方法

プロジェクトのドキュメントを作成する上で一番難しいことは、ドキュメントを正確かつ最新に保つことです。コードリポジトリの中にドキュメント保存用の領域を作ることで、それがずっと簡単になります。

そのような置き場を設置したら、開発者がモジュールに変更を加える時にはいつも、関連するドキュメントにも変更を加えるべきです。

この作業は大型のプロジェクトでは極めて困難になることもあるでしょう。その場合、モジュールのヘッダーに関連するドキュメントのリストを追加すると簡単になります。

ドキュメントが常に正しいということを保証するための補助的なやり方としては、doctestを通じて、ドキュメントとテストを一体化してしまう方法があります。

これらに関しては、テスト駆動開発やドキュメント駆動開発の原則について説明を行う、次章で触れていきます。