次のステップへ¶
さあ、ここにきたあなたは、入門編 をあらかた読み終えて、 Django を使い続ける決心をしたことだと思います。入門編では、Django のほんの表面的な部分に触れただけにすぎません (実際、入門編の分量は、全体のドキュメントの 5% にも満たないのです)。
さて、次は何をしましょうか？
そうですね、私たちは「なすことによって学ぶ (learning by doing)」ことがとても大好きですよね。今や、読者のみなさんは自分のプロジェクトを作成して、いろいろと遊んでみるのに十分な段階にあります。もし新しい技を学ぶ必要が出てきたら、その時は、いつでもここに戻って来てください。
私たちは、Django のドキュメントを有用で明確で、可能な限り完全なものにするための努力を多くしてきました。このドキュメントの残りの部分は、ドキュメントがどのように機能するのかをより詳しく説明しています。
(そう、これはいわばドキュメントのドキュメントです。ただし、このドキュメントのドキュメントの読み方を説明するドキュメント、などといったものを書いたりはしませんから、安心してくださいね。)
ドキュメントの探し方¶
Djangoにはたくさんのドキュメント -- （ 約450,000語）があるので、必要なものを見つけるのは難しい場合があります。開始するのに適した場所は、索引 です。また、組み込みの検索機能を使用することをお勧めします。
もちろん、片っ端から読み進むのもいいですけどね。
ドキュメントの構成¶
Django のドキュメントは、用途に応じていくつかのセクションに分かれています。
introductory material は、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 の開発版 (別名 main ブランチ) を使っているなら、docs/ ディレクトリに全てのドキュメントが入っています。チェックアウトした Git ブランチを更新すれば、最新版が取得できます。
テキストドキュメントの便利でローテクな使い方の一つに Unix の grep ユーティリティを使った全ドキュメント検索があります。例えば、以下のようにすれば、 “max_length” について触れている部分を表示できます:
$ grep -r max_length /path/to/django/docs/
...\> grep -r max_length \path\to\django\docs\
ローカルで HTML で読む¶
以下の簡単なステップを踏めば、 HTML ドキュメントのローカルコピーを手に入れられます。
Django のドキュメントは、 Sphinx というシステムを使ってプレーンテキストから HTML への変換を行っています。 Sphinx のウェブサイトから Sphinx をダウンロードしてインストールするか、次のコマンドで
pipを使ってインストールします。$ python -m pip install Sphinx
...\> py -m 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 リポジトリの main ブランチにあるテキストドキュメントには、「最新かつ最大の」変更と追加が含まれています。これらの変更には、Django の次の 機能リリース を対象とした新機能のドキュメントが含まれています。そのため、Django の最近の変更や追加をハイライトするというポリシーを指摘しておきましょう。
私たちは以下の方針に従います。
- https://docs.djangoproject.com/en/dev/ にある開発ドキュメントは、main ブランチから生成されます。これらのドキュメントは、最新の機能リリースに加え、それ以降フレームワークで追加/変更された機能に対応しています。
- Django の開発版に機能を追加する場合、同じ Git のコミットトランザクションの中で、ドキュメントの変更もコミットします。
- ドキュメント内で追加/変更された機能を区別するために、まだリリースされていないバージョンの場合、「Django の開発バージョンで新たに追加された機能です (New in Django Development version)」 というフレーズを、リリースバージョンの場合、「バージョン X.Y で新たに追加された機能です (New in version X.Y)」 というフレーズを使います。
- ドキュメントの修正や改善は、マージする人の判断で、最新リリースブランチにバックポートされることがあります。しかし、あるバージョンが サポート終了 の状態にされた場合、そのバージョンのドキュメントは、それ以上いかなる更新もされません。
- Web のドキュメントのメインページ には、以前のバージョンのドキュメントへのリンクがあります。読んでいるドキュメントのバージョンが、現在使っている Django のバージョンと同一のものであるか、十分に注意してください！
