次のステップへ¶
さあ、ここにきたあなたは、入門編 をあらかた読み終えて、 Django を使い続ける決心をしたことだと思います。入門編では、Django のほんの表面的な部分に触れただけにすぎません (実際、入門編の分量は、全体のドキュメントの 5% にも満たないのです)。
さて、次は何をしましょうか？
そうですね、私たちは「なすことによって学ぶ (learning by doing)」ことがとても大好きですよね。今や、読者のみなさんは自分のプロジェクトを作成して、いろいろと遊んでみるのに十分な段階にあります。もし新しい技を学ぶ必要が出てきたら、その時は、いつでもここに戻って来てください。
私たちは、Django ドキュメントを有意義で、読みやすく、可能な限り完全なものにしようと努力しています。このドキュメントの残りの部分では、読者の皆さんが Django のドキュメントをできるだけ活用できるように、ドキュメントがどういうしくみになっているのかを説明しています。
(そう、これはいわばドキュメントのドキュメントです。ただし、このドキュメントのドキュメントの読み方を説明するドキュメント、などといったものを書いたりはしませんから、安心してくださいね。)
ドキュメントの探し方¶
Django には多くのドキュメントがあり、その分量は今や 450,000 語以上になります（現在も増えています）。その中から必要なものを捜し出すのは大変です。そういうときは、 検索ページ や 索引 から辿るとよいでしょう。
もちろん、片っ端から読み進むのもいいですけどね。
ドキュメントの構成¶
Django のドキュメントは、用途に応じていくつかのセクションに分かれています。
入門編 は、Django やウェブ開発全般の初心者を対象に作られています。あまり詳細な解説はありませんが、Django の開発が「どのようなものか」を高い視点から見られます。
一方、トピック別ガイド では、Django の個々の構成要素について詳しく解説しています。このセクションでは、Django の モデルシステム、テンプレートエンジン、フォームフレームワーク などといったトピックを解説しています。
おそらく、読者の皆さんは、このセクションを読み進むのに、大部分の時間を使うでしょう。このガイドを全て読破すれば、Django を扱う上で必要なことのほとんどを知ることができるはずです。
ウェブ開発に必要な知識は、いくつもの領域にまたがって広く浅く分布しているものです。このセクションには、「〜をするにはどうしたらよいか？」というような質問に答えてくれる How-to が集まっています。たとえば、Django で PDF を生成する方法 や、テンプレートタグを自作する方法 などの How-to があります。
よくある質問は、これとは別に FAQ で扱っています。
ガイドや How-to ドキュメントでは、Django のクラスや関数、メソッドのすべてを解説しているわけではありません。初めて Django を学ぼうとする人に一度に全てを教えようとしても、教えたことが記憶からあふれてしまうからです。その代わりに、一つひとつのクラスや関数、メソッド、モジュールの詳しい解説は、 リファレンス に書いてあります。特定の関数の仕様や、使える機能を調べたい場合には、このセクションを参照してください。
公開用にプロジェクトをデプロイする方法について知りたければ、さまざまなデプロイ環境に対応した いくつかのガイド を用意しています。デプロイ時に考えなくてはいけないことをリストアップした デプロイ時チェックリストdeployment checklist と合わせて読んでみてください。
最後に、ほとんどの開発者にとってはあまり関係のない「特殊な」ドキュメントとして、 リリースノート、Django 自体にコードを追加したい人のための 内部使用のドキュメント、そして、分類が難しいその他のドキュメント があります。
ドキュメントの更新の方針¶
Django のコードベースが毎日のように開発と改良を重ねているように、ドキュメントも常に改良を重ねています。ドキュメントの改良は以下のような理由に基づいて 行われます。
- 文法やタイプミスなどの誤りを修正する場合。
- 既存の内容に対して、新たに情報や例題を追加する場合。
- まだ解説されていない Django の機能をドキュメント化する場合 (未ドキュメントの機能は減りつつありますが、まだいくつか残っています)。
- 新たな機能が追加され、ドキュメントも追加する場合。あるいは、Django の API や挙動が変更された場合。
Django のドキュメントはコードと同じソースコード管理システム下にあり、 Git リポジトリの docs ディレクトリ以下に置かれています。オンラインで表示される各ドキュメントは、レポジトリ上でそれぞれ別々のテキストファイルに分かれています。
ドキュメントの入手¶
Django のドキュメントを入手するにはいくつか方法があります。おすすめの順に以 下に示します。
Web 版¶
Django ドキュメントの最新版は https://docs.djangoproject.com/en/dev/ にあります。ここにある HTML ページは、ソースコード管理システム上のテキストファイルから自動生成されているものです。したがって、これらのファイルは「最新最良の」 Django に対応しています。つまり、最近の修正や追加事項を反映していて、 まだ開発版でしか使えないような最新の機能についても部分的に解説しているわけです。(後述の「バージョン間の相違点」を参照してください。)
ドキュメント改良のお手伝いは大歓迎です。変更すべき点、修正すべき点、改良す べき点などを チケットシステム に提出してください。Django の開発陣はチケットシステムを監視して、あなたのフィードバックが皆に恩恵をもたらすようにドキュメントを改良しています。
ただし、チケットは一般的なテクニカルサポートに関わる質問ではなく、ドキュメント自体に関する内容にしてください。 Django のセットアップに関する個別の問 題はドキュメントのコメント欄にではなく、 django-users メーリングリストや IRC の #django チャネル にお願いします。
プレーンテキスト版¶
オフラインで読みたい人や、あるいは単に利便性のために、Django ドキュメントはプレーンテキスト形式でも読めます。
Django の公式リリース版を使っているなら、ソースコードのアーカイブパッケージ (tarball) に docs/ ディレクトリが入っています。このディレクトリには各リリースの全てのドキュメントが入っています。
Django の開発版 (別名 “trunk”) を使っている場合、docs/ ディレクトリに全てのドキュメントが入っています。最新版を取得したければ、Git checkout を実行してください。
テキストドキュメントの便利でローテクな使い方の一つに Unix の grep ユーティリティを使った全ドキュメント検索があります。例えば、以下のようにすれば、 “max_length” について触れている部分を表示できます:
$ grep -r max_length /path/to/django/docs/
ローカルで HTML で読む¶
以下の簡単なステップを踏めば、 HTML ドキュメントのローカルコピーを手に入れられます。
Django のドキュメントは、 Sphinx というシステムを使ってプレーンテキストから HTML への変換を行っています。 Sphinx のウェブサイトから Sphinx をダウンロードしてインストールするか、次のコマンドで
pipを使ってインストールします。$ pip install Sphinxそして、次のコマンドで、Django のドキュメントディレクトリにある
Makefileを使って、ドキュメントを HTML に変換するだけです。$ cd path/to/django/docs $ make html
これを実行するには、GNU Make がインストールされている必要があります。
もし Windows の場合は、ドキュメントディレクトリにあるバッチファイルを使用して変換できます。
cd path\to\django\docs make.bat htmlHTML ドキュメントが
docs/_build/htmlに生成されます。
バージョンごとの違い¶
前述したように、 Git リポジトリに入っているテキストドキュメントは変更や追加によって「最新最良」の状態にあります。変更によって、開発版、すなわち Git (“trunk”) 版の Django に新たに登場した機能がテキストに記載されることがよくあります。このため、Django の各バージョン間で一貫したドキュメンテーションポリシをここで示しておきます。
私たちは以下の方針に従います。
- djangoproject.com の第一のドキュメントは Git の 最新の docs から生成される HTML 形式のドキュメントです。これらのドキュメントは、常に最新の Django 公式リリースと、最新のリリース 以後 に追加／変更された機能に対応しています。
- Django の開発版に機能を追加する場合、可能ならば、同じ Git のコミットトランザクションにおいて、ドキュメントの変更もコミットします。
- 追加／変更された機能を区別するため、「バージョン X.Y で新たに追加された機能です (New in version X.Y)」 というフレーズを使います。X.Y は次の (開発中の) リリースバージョンです。
- ドキュメントの修正や改善は、コミッターの判断により、最後のリリースブランチにバックポートされることがあります。しかし、あるバージョンが サポート終了 の状態にされた場合、そのバージョンのドキュメントは、それ以上いかなる更新もされません。
- Web のドキュメントのメインページ には、以前の全てのバージョンのドキュメントへのリンクがあるので、今使っている Django のバージョンと、今読んでいるドキュメントのバージョンとが、ちゃんと同じものであるか、十分に注意するようにしてください！
