自分自身のポートフォリオを構築する

これまでの説明で紹介してきたテンプレートは、あなたのソフトウェアのドキュメント作成に使用することができる基盤となります。ここからは、Pasterを使用して、自分自身のドキュメントのポートフォリオを構築するために、それ以外のテンプレートを追加するための方法を紹介していきます。

プロジェクト中に作成するドキュメントの量に関しては、必要最低限で、十分というのを心がけてください。追加されるそれぞれのドキュメントについても、対象となる読者を明確に定義し、実際のニーズを満たすようにします。実際に価値の増加に寄与しないドキュメントは書くべきではありません。

ドキュメントのランドスケープの構築

前節で説明をしてきたドキュメントポートフォリオによって、複数の種類のドキュメントが提供されますが、読者の手に渡った後でそのドキュメントを再グループ化したり、再構成したりする方法は提供されません。読者がドキュメントにざっと目を通すときに、心の中でドキュメントのインデックスページのようなものを作成してそれを参照します。Andreas Rupingは、これをドキュメントランドスケープと呼んでいます。彼は、ドキュメントを組織化するための最適な手法は、ロジカルツリーを構築する方法であるという結論づけています。

注釈

(Tarekによる補足)田舎に行って景色を見ると木々や平地、家々などを見ることができますが、このようなさまざまな要素が含まれる景色をランドスケープと呼びます。ドキュメントランドスケープもこれと同じく、レシピ、チュートリアルなどの多くのドキュメントからなります。ランドスケープは目次、イメージマップなどのさまざまな形式で表現することもできます。読者や作成者ごとのランドスケープを用意することもできます。

言い換えると、ポートフォリオを構成するドキュメントごとに、ディレクトリツリー内に配置するべき場所を見つける必要があるということです。この場所というのは、ドキュメント作成者が作成するとき、もしくはドキュメントの読者がそれを探すときの、どちらの場合においてもわかりやすい必要があります。

ドキュメントを探索する上で手助けとなるのは、作成者と読者の両方が読むことができるように、それぞれのレベルで目次のページを作ることです。

ドキュメントのランドスケープの構築は、次の2つのステップで行うことができます。

  • 制作者向けのツリーの構築
  • 顧客のためのツリーを構築し、制作者向けのツリーの上位の配置する

制作者と顧客は異なった場所で、異なった形式のドキュメントにアクセスするので、制作者と顧客を明確に区別することが大切です。

制作者のレイアウト

制作者の視点から見た場合、それぞれのドキュメントは、Pythonモジュールと同じように処理されます。ドキュメントはバージョン管理システムに格納され、コードと同じように扱われます。

作成者は、自分が作成している文章が最終的にどのような外見になるのか、ということを気にしません。彼らが確実に行いたいのは、適切な場所に目的のドキュメントを書くことです。

フォルダのツリーに保存されたreStructuredTextのファイルは、バージョン管理システムを使用して、ソフトウェアのコードと一緒に管理することができます。この方法は、制作者向けのドキュメントのランドスケープを構築するための便利な方法です。

6章で説明したのAtomisatorの中で紹介したフォルダ構造を振り返ってみると、このツリーのルートにある//tt{docs//tt}フォルダを使用することができることがわかります。

このツリーを組織化するためのもっともシンプルな方法は、特性に従ってドキュメントをグループにすることです。

$ cd atomisator
$ find docs
docs
docs/source
docs/source/design
docs/source/operations
docs/source/usage
docs/source/usage/cookbook
docs/source/usage/modules
docs/source/usage/tutorial

このdocsフォルダでは、次節で使用するツールで利用出来るようにするため、ドキュメントをsourceフォルダの下に格納している点に注意してください。

ルート以外のそれぞれのレベルには、index.txtというファイルを追加することができます。これは、どのような種類のドキュメントがそのフォルダに含まれているのかというのを説明したり、それぞれのサブフォルダに何が含まれているのかというサマリーを書くことができます。例えば、運用フォルダの場合には、読むことができる運用ドキュメントのリストを含めます。

==========
Operations
==========

This section contains operations documents:

- How to install and run Atomisator
- How to install and manage a PostgreSQL database
for Atomisator
====
運用
====

このセクションには運用に関するドキュメントが含まれます:

- Atomisatorのインストールと実行方法
- Atomisatorで使用する、PostgreSQLのデータベースのインストールと管理

作成した人が更新するのを忘れないように、自動生成したリストを使用する方法もあるでしょう。

顧客のレイアウト

顧客の視点から考えると、目次を見て概要を掴んだり、ドキュメント全体がきちんとフォーマットされていて、読みやすく、なおかつ見た目が良いということが重要になります。

フォーマットとしては、ウェブページがベストな選択肢です。reStructuredTextのファイルから生成するのも簡単です。

Sphinx (http://sphinx.pocoo.org) を使用すると、テキストのツリーから、構造化されたHTMLを生成することができます。Sphinxはいくつかのスクリプトと、docutils拡張で作られています。このツールはPython本体のドキュメントも含め、多くのプロジェクトのドキュメント作成のツールとして使用されています。組み込みの機能にはさまざまなものがあり、本当にすばらしいナビゲーションや、JavaScriptで実装されクライアントサイドで動作する、軽量だが十分な機能を持つ検索エンジンと一緒にコンテンツを生成します。また、コードのサンプルをレンダリングするにはPygmentsを使用しているため、見た目のすばらしいシンタックスハイライトも行われます。

本節の前半で定義したドキュメントのランドスケープの設定も、Sphinxを使うと容易に行えます。

Sphinxのインストールには、easy_installを使用します:

$ sudo easy_install Sphinx
Searching for Sphinx
Reading http://cheeseshop.python.org/pypi/Sphinx/
...
Finished processing dependencies for Sphinx

インストールを行うと、sphinx-quickstartなどのいくつかのスクリプトがインストールされます。このスクリプトを実行すると、Webのドキュメントを生成するために使用するスクリプトや、Makefileを生成します。docsフォルダの中でこのスクリプトを実行して、次のように質問に答えていきます。

$ sphinx-quickstart
Welcome to the Sphinx quickstart utility.

Enter the root path for documentation.
> Root path for the documentation [.]:
> Separate source and build directories (y/n) [n]: y
> Name prefix for templates and static dir [.]:
> Project name: Atomisator
> Author name(s): Tarek Ziade
> Project version: 0.1.0
> Project release [0.1.0]:
> Source file suffix [.rst]: .txt
> Name of your master document (without suffix) [index]:
> Create Makefile? (y/n) [y]: y

Finished: An initial directory structure has been created.

You should now populate your master file ./source/index.txt and create
other documentation
source files. Use the sphinx-build.py script to build the docs, like so:

   make <builder>

このスクリプトを実行すると、conf.pyというファイルがsourceフォルダの中に追加されます。このファイルには、質問に回答して定義された設定が含まれます。それ以外には、スクリプトを実行したフォルダのルートにindex.txtと、Makefileも生成されます。

make htmlを実行すると、buildディレクトリの中にツリーを生成されます。

$ make html
mkdir -p build/html build/doctrees
sphinx-build.py -b html -d build/doctrees -D latex_paper_size=  source
build/html
Sphinx v0.1.61611, building html
trying to load pickled env... done
building [html]: targets for 0 source files that are out of date
updating environment: 0 added, 0 changed, 0 removed
creating index...
writing output... index
finishing...
writing additional files...
copying static files...
dumping search index...
build succeeded.
Build finished. The HTML pages are in build/html.

build/htmlディレクトリの中にドキュメントが生成されます。index.htmlをブラウザで開いて読むことができます。

../../_images/sphinx.png

ソースコードから生成されたHTML版のドキュメント以外にも、モジュールリストや索引などのページが自動的に生成されます。Sphinxでは、これらの機能のためにdocutilsを拡張しています。主に次の項目が、拡張された箇所です。

  • 目次を構築するためのディレクティブ
  • ドキュメントをモジュールヘルパーとして登録するためのマーカー
  • 索引に項目を追加するためのマーカー

インデックスのページでの作業

Sphinxではtoctreeディレクティブが用意されています。これは、ドキュメント内に目次を挿入して、他のドキュメントへのリンクを張るために使用します。ディレクティブ内のそれぞれの行は、現在のドキュメントからの相対パスで書かれたファイル名でなければなりません。globスタイルの名前を使用して、式にマッチする複数ファイルをまとめて登録する機能も提供されています。

例えば、制作者のランドスケープで定義した、cookbookフォルダのindexファイルは次のような内容になるでしょう。

============
クックブック
============

クックブックへようこそ!

現在利用可能なレシピ:

.. toctree::
  :glob:

  *

このような文法に従ってソースに書いてビルドすると、cookbookフォルダ内にある、利用可能なすべてのreStructuredTextのリストが表示されるようになります。このディレクティブは、ブラウズ可能なドキュメントにビルドされるすべてのindexファイル内で利用することができます。

モジュールヘルパーの登録

モジュールヘルパーのドキュメントで使用できる機能として、モジュールのマーカーを追加することができます。これを書くと、モジュールの索引ページから参照することができるようになります。

=======
session
=======

.. module:: db.session

このsessionモジュールでは...

モジュール名の衝突を防ぐために使用される、dbという名前空間がここで設定されていることに注意してください。Sphinxはこれをモジュールのカテゴリとして使用します。図では1つしかありませんが、db.という名前で始まるすべてのモジュールがグループにまとめられて表示されます。

../../_images/sphinx-module-index.png

Atomisatorのの場合にはdb, feed, main, parserというパッケージが、モジュールのグループ化に利用されるでしょう。

あなたのドキュメントでも、多くのモジュールが含まれる場合に、この機能を使用することができます。

注釈

最初の方で作成したモジュールヘルパーのテンプレート(pbp_module_doc)を変更して、デフォルトで、このmoduleディレクティブを追加するようにできます。

索引のマーカーの追加

モジュール以外にも、索引ページに、ドキュメント内の要素へのリンクを追加するためのオプションを使用することができます。

.. index::
   single: データベースアクセス
   single: セッション

=======
session
=======

.. module:: db.session

このsessionモジュールでは...

"データベースアクセス"と"セッション"の、2つの新しい項目が索引ページに追加されます。

クロス・リファレンス

最後になりますが、Sphinxではクロス・リファレンスの設定を行うためのインラインマークアップも提供されています。例えば、次のように書くと、指定されたモジュールへのリンクを作成することができます。

:mod:`db.session`

:mod:というのは、モジュールを表すマーカーです。db.sessionというのはリンクを張ろうと思っているモジュールの名前になります。このリンク先のドキュメントは、どこかで登録しておく必要があります。:mod:もそうですが、これまで説明してきた項目はSphinxによってreStructuredTextに追加された、特別なディレクティブです。

注釈

Sphinxはもっと多くの機能を提供しています。それらの情報はウェブサイトで見ることができます。たとえば、autodoc機能は、ドキュメントを構築する際にdoctestを自動収集することができる、すばらしいオプションになります。詳しくはhttp://sphinx.pocoo.orgを参照してください。[1]

脚注

[1]日本語訳はhttp://sphinx-users.jp/doc.htmlを参照してください。