Django ドキュメントの読み方

revision-up-to:5613 (0.97pre SVN)

私達は， Django のドキュメントが，有用で読みやすくできるだけ詳細であるよう 多大な努力を投じています．ここでは，ドキュメントを活用するコツと，ドキュメ ントを書くときのスタイルガイドラインを示します．

(そう，これはドキュメントのドキュメントです．ドキュメントの読み方の読み方に ついてドキュメント化するつもりはありませんから，安心してください．)

ドキュメント更新の方針

Django のコードベースが毎日のように開発と改良を重ねているように，ドキュメン トも常に改良を重ねています．ドキュメントの改良は以下のような理由に基づいて 行われます:

  • 文法やタイプミスなどの誤りを修正する場合．
  • 既存の内容に対して，新たに情報や例題を追加する場合．
  • まだ解説されていない Django の機能をドキュメント化する場合 (未ドキュ メントの機能は減りつつありますが，まだいくつか残っています)．
  • 新たな機能が追加され，ドキュメントも追加する場合．あるいは， Django の API や挙動が変更された場合．

Django のドキュメントはコードと同じソースコード管理システム下にあり， Subversion リポジトリの django/trunk/docs ディレクトリ以下に置かれていま す．各ドキュメントは，例えば「汎用ビュー」フレームワークや，データベースモ デルの構築方法といった具合に，個別のトピックごとに別々のテキストファイルに なっています．

ドキュメントの入手

Django のドキュメントを入手するにはいくつか方法があります．おすすめの順に以 下に示します:

Web から

Django ドキュメントの最新版は http://www.djangoproject.com/documentation/ にあります．ここにある HTML ページは，ソースコード管理システム上のテキスト ファイルから自動生成されているものです．従って，これらのファイルは「最新最 良の」 Django に対応しています．つまり，最近の修正や追加事項を反映していて， まだ開発版でしか使えないような最新の機能についても部分的に解説しているわけ です (下記の バージョン間の相違点 を参照してください)．

ドキュメント改良のお手伝いは大歓迎です．変更すべき点，修正すべき点，改良す べき点などを チケットシステム に提出してください．Django の開発陣がチケッ トシステムを監視して，あなたのフィードバックが皆に恩恵をもたらすようにしま す．ただし，コメントを投稿するときは，一般的なテクニカルサポートに関わる質 問ではなく，ドキュメント自体に関する内容にしてください． Django の構成に関 する個別の問題はドキュメントのコメント欄にではなく， django-users メーリングリスト や IRC の #django チャネル にお願いしま す．

プレーンテキスト

オフラインでテキストを読む方が便利なら，プレーンテキスト形式で Django ドキュ メントを読めます．

Django の公式リリース版を使っているなら，ソースコードのアーカイブパッケージ (tarball) に docs/ ディレクトリが入っています．このディレクトリには各リ リースの全てのドキュメントが入っています．

Django の開発版 (いわゆる Subversion "trunk") を使っている場合， docs/ ディレクトリに全てのドキュメントが入っています．最新版を取得したければ， Python コードの更新と同様， svn update を実行してください．

最新の Django ドキュメントを Subversion から取り出すには，以下のようなシェ ルコマンドを使います:

svn co http://code.djangoproject.com/svn/django/trunk/docs/ django_docs

テキストドキュメントの便利でローテクな使い方の一つに Unix の grep ユー ティリティを使った全ドキュメント検索があります．例えば，以下のようにすれば， "edit_inline" について触ている部分を表示できます:

grep edit_inline /path/to/django/docs/*.txt

フォーマット変換

テキストドキュメントは ReST (ReStructuredText) 形式で書かれています． ReST はただ単体でも読みやすいだけでなく， HTML のような他のフォーマットにも簡単 に変換できるようになっています． reStructuredText ライブラリをインストー ルしていれば， rst2html を使って HTML ファイルを生成できます．

バージョン間の相違点

前述したように， Subversion リポジトリに入っているテキストドキュメントは 変更や追加によって「最新最良」の状態にあります．変更によって，開発版，すな わち Subverion ("trunk") 版の Django に新たに登場した機能がテキストに記載さ れることがよくあります．このため， Django の各バージョン間で一貫したドキュ メンテーションポリシをここで示しておきます．

我々は，以下のポリシに従っています:

  • djangoproject.com の第一のドキュメントは Subversion から生成される HTML 形式のドキュメントです．これらのドキュメントは常に最新の Django 公式リリースと，最新のリリース 以後 に追加／変更された機能に対応し ています．
  • Django の開発版に機能を追加する場合，可能ならば同じ Subversion のコミッ トトランザクションにおいてドキュメントの変更もチェックインします．
  • 追加／変更された機能を区別するため， (開発版の Django で新たに追加された機能です (New in Django development version) という文を使います．このため， djangoproject.com で公開されている最新のドキュメントは，最新のリリー ス および 開発版のユーザの両方から利用できます．
  • 特定のリリース版のドキュメントは，公式リリース時に一度フリーズされま す．従って，ドキュメントはその時のスナップショットになります．以前の バージョンに遡ってセキュリティアップデートその他の変更を行った場合に のみ，例外的にドキュメントを更新します．ドキュメントのフリーズ後は， 各ドキュメントの冒頭に "These docs are frozen for Django version XXX" という一文と，ドキュメントの最新版へのリンクを追加します．
  • Web のドキュメントメインページ には，以前の全てのバージョンのドキュ メントに対するリンクがあります．