次のステップへ¶
さあ、ここにきたあなたは、入門編 をあらかた読み終えて、 Django を使い続ける決心をしたことだと思います。入門編では、Django のほんの表面的な部分に触れただけにすぎません (実際、入門編の分量は、全体のドキュメントの 5% にも満たないのです)。
さて、次は何をしましょうか？
そうですね、私たちは「なすことによって学ぶ (learning by doing)」ことがとても大好きですよね。今や、読者のみなさんは自分のプロジェクトを作成して、いろいろと遊んでみるのに十分な段階にあります。もし新しい技を学ぶ必要が出てきたら、その時は、いつでもここに戻って来てください。
We've put a lot of effort into making Django's documentation useful, clear and as complete as possible. The rest of this document explains more about how the documentation works so that you can get the most out of it.
(そう、これはいわばドキュメントのドキュメントです。ただし、このドキュメントのドキュメントの読み方を説明するドキュメント、などといったものを書いたりはしませんから、安心してくださいね。)
ドキュメントの探し方¶
Django には多くのドキュメントがあり、その分量は今や 450,000 語以上になります（現在も増えています）。その中から必要なものを捜し出すのは大変です。そういうときは、 検索ページ や 索引 から辿るとよいでしょう。
もちろん、片っ端から読み進むのもいいですけどね。
ドキュメントの構成¶
Django のドキュメントは、用途に応じていくつかのセクションに分かれています。
入門編 は、Django やウェブ開発全般の初心者を対象に作られています。あまり詳細な解説はありませんが、Django の開発が「どのようなものか」を高い視点から見られます。
一方、トピック別ガイド では、Django の個々の構成要素について詳しく解説しています。このセクションでは、Django の モデルシステム、テンプレートエンジン、フォームフレームワーク などといったトピックを解説しています。
おそらく、読者の皆さんは、このセクションを読み進むのに、大部分の時間を使うでしょう。このガイドを全て読破すれば、Django を扱う上で必要なことのほとんどを知ることができるはずです。
ウェブ開発に必要な知識は、いくつもの領域にまたがって広く浅く分布しているものです。このセクションには、「〜をするにはどうしたらよいか？」というような質問に答えてくれる How-to が集まっています。たとえば、Django で PDF を生成する方法 や、テンプレートタグを自作する方法 などの How-to があります。
よくある質問は、これとは別に FAQ で扱っています。
ガイドや How-to ドキュメントでは、Django のクラスや関数、メソッドのすべてを解説しているわけではありません。初めて Django を学ぼうとする人に一度に全てを教えようとしても、教えたことが記憶からあふれてしまうからです。その代わりに、一つひとつのクラスや関数、メソッド、モジュールの詳しい解説は、 リファレンス に書いてあります。特定の関数の仕様や、使える機能を調べたい場合には、このセクションを参照してください。
公開用にプロジェクトをデプロイする方法について知りたければ、さまざまなデプロイ環境に対応した いくつかのガイド を用意しています。デプロイ時に考えなくてはいけないことをリストアップした デプロイ時チェックリストdeployment checklist と合わせて読んでみてください。
Finally, there's some "specialized" documentation not usually relevant to most developers. This includes the release notes and internals documentation for those who want to add code to Django itself, and a few other things that don't fit elsewhere.
ドキュメントの更新の方針¶
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 の開発版 (別名 master ブランチ) を使っているなら、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に生成されます。
バージョンごとの違い¶
The text documentation in the master branch of the Git repository contains the "latest and greatest" changes and additions. These changes include documentation of new features targeted for Django's next feature release. For that reason, it's worth pointing out our policy to highlight recent changes and additions to Django.
私たちは以下の方針に従います。
- https://docs.djangoproject.com/en/dev/ にある開発ドキュメントは、master ブランチから生成されます。これらのドキュメントは、最新の機能リリースに加え、それ以降フレームワークで追加/変更された機能に対応しています。
- Django の開発版に機能を追加する場合、同じ Git のコミットトランザクションの中で、ドキュメントの変更もコミットします。
- ドキュメント内で追加/変更された機能を区別するために、まだリリースされていないバージョンの場合、「Django の開発バージョンで新たに追加された機能です (New in Django Development version)」 というフレーズを、リリースバージョンの場合、「バージョン X.Y で新たに追加された機能です (New in version X.Y)」 というフレーズを使います。
- ドキュメントの修正や改善は、コミッターの判断で、最新リリースブランチにバックポートされることがあります。しかし、あるバージョンが サポート終了 の状態にされた場合、そのバージョンのドキュメントは、それ以上いかなる更新もされません。
- Web のドキュメントのメインページ には、以前のバージョンのドキュメントへのリンクがあります。読んでいるドキュメントのバージョンが、現在使っている Django のバージョンと同一のものであるか、十分に注意してください！
