さあ、ここにきたあなたは、入門編 をあらかた読み終えて、 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 のドキュメントはコードと同じソースコード管理システム下にあり、 Git リポジトリの docs ディレクトリ以下に置かれています。オンラインで表示される各ドキュメントは、レポジトリ上でそれぞれ別々のテキストファイルに分かれています。
Django のドキュメントを入手するにはいくつか方法があります。おすすめの順に以 下に示します。
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 ドキュメントのローカルコピーを手に入れられます。
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 html
HTML ドキュメントが 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.
私たちは以下の方針に従います。
8月 03, 2020