| revision-up-to: | 8961 (1.0) |
|---|
さあ、ここにきたあなたは、 入門編 をあらかた読み終えて、 Django を使い続ける決心をしたことだと思います。入門編では、 Django のほんの 表面的な部分に触れただけにすぎません (実際、入門編の分量は、全体のドキュメ ントの 10% にも満たないのです)。
さて、次は何をしましょうか？
そうですね、私達は実践を通して学ぶのがとても大好きですよね。今や、読者のみ なさんは自分のプロジェクトを作成して、いろいろと遊んでみるのに十分な段階に あります。新しい技を身に付けたければ、いつでもここに戻って来てください。
私達は、 Django ドキュメントを有意義で、読みやすく、可能な限り完璧にしよう と努力しています。このドキュメントの残りの部分では、読者の皆さんが Django のドキュメントをできるだけ活用できるように、ドキュメントがどういう仕組みに なっているのかを説明しています。
(そう、これはいわばドキュメントのドキュメントです。ただし、このドキュメント の読み方を説明するドキュメントを書いたりはしませんから心配しないでください ね。)
Django には、いまや 200,000 語を越す たくさん のドキュメントがあります。 その中から必要なものを捜し出すのは大変です。そういうときは、 Search Page や Index から辿るとよいでしょう。
もちろん、片っ端から読み進むのもいいですけどね。
Django のドキュメントは、用途に応じていくつかの塊に分けられています:
入門編 は、 Django や、ウェブ開発全般の初心者を 対象に作られています。あまり詳細な解説はありませんが、高い視点で Django の開発が「どのようなものか」を見られます。
トピック別ガイド では、 Django の個々の構成要素 について詳しく解説しています。このセクションでは、 Django の モデルシステム, テンプレートエンジン, フォームフレームワーク といったトピックを解説しています。
おそらく、読者の皆さんはこのセクションを読み進むのに多くの時間を費す でしょう。このガイドを全て読破したら、 Django を扱う上で必要なことは ほとんど知っているはずです。
ウェブ開発に必要な知識は、いくつもの領域にまたがって広く、浅く分布し ているものです。 このセクションには、「〜をするにはどうしたらよいです か？」といった質問に答える、 HOWTO が書かれて います。例えば、 Django で PDF を生成する方法 や、 テンプレートタグを自作する方法 などです。
よくある質問は、これとは別に FAQ で扱っています。
ガイドや HOWTO ドキュメントは、 Django の全てのクラスや関数、メソッ ドを解説しているわけではありません。 Django を学ぼうとする人に最初か ら全てを教えようとしても、溢れてしまうからです。その代わりに、個々の クラスや関数、メソッド、モジュールの解説を リファレンス に置きました。特定の関数の仕様や、どんな機能を使えるかを 調べたければ、このセクションを参照してください。
最後に、ほとんどの開発者にとってはあまり関係のない「特殊な」ドキュメ ントとして、 リリースノート, 撤廃された機能のドキュメント, Django 自体にコー ドを追加したい人のための 内部仕様のドキュメント, そして その他、分類の難しい雑多なドキュメン ト があります。
Django のコードベースが毎日のように開発と改良を重ねているように、ドキュメン トも常に改良を重ねています。ドキュメントの改良は以下のような理由に基づいて 行われます:
Django のドキュメントはコードと同じソースコード管理システム下にあり、 Subversion リポジトリの django/trunk/docs ディレクトリ以下に置かれていま す。各ドキュメントは、例えば「汎用ビュー」フレームワークや、データベースモ デルの構築方法といった具合に、個別のトピックごとに別々のテキストファイルに なっています。
Django のドキュメントを入手するにはいくつか方法があります。おすすめの順に以 下に示します:
Django ドキュメントの最新版は http://docs.djangoproject.com/en/dev/ にあります。ここにある 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 ユー ティリティを使った全ドキュメント検索があります。例えば、以下のようにすれば、 "max_length" について触ている部分を表示できます:
$ grep -r max_length /path/to/django/docs/
以下のステップを踏めば、 HTML ドキュメントのローカルコピーを手に入れられま す:
Django のドキュメントは、 Sphinx というシステムを使ってプレーンテキ ストから HTML への変換を行っています。 Sphinx のウェブサイトから Sphinx をダウンロードしてインストールするか、 Python の easy_install を使ってインストールします:
$ easy_install Sphinx
Django のドキュメントディレクトリにある Makefile を使って、ドキュ メントを HTML に変換します:
$ cd path/to/django/docs
$ make html
GNU Make がインストールされている必要があります。
HTML ドキュメントが docs/_build/html に生成されます。
Warning
この節を書いている時点では、 Django はリリース前の Sphinx を使っていま す。そのため、ソースコードから Sphinx をインストールせねばなりません。 この問題はすぐに修正する予定です。
(訳注: バージョン 0.4.1 または trunk の Sphinx を使ってください。)
前述したように、 Subversion リポジトリに入っているテキストドキュメントは 変更や追加によって「最新最良」の状態にあります。変更によって、開発版、すな わち Subverion ("trunk") 版の Django に新たに登場した機能がテキストに記載さ れることがよくあります。このため、 Django の各バージョン間で一貫したドキュ メンテーションポリシをここで示しておきます。
我々は、以下のポリシに従っています:
Aug 31, 2012