Django 2.2.9.dev20191202104323 ドキュメント

Home | Table of contents | Index | Modules
« previous | up | next »

次のステップへ¶

さあ、ここにきたあなたは、入門編 をあらかた読み終えて、 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 の開発版 (別名 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 を使ってインストールします。

    $ pip install Sphinx
    
    ...\> 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 に生成されます。

バージョンごとの違い¶

Gitリポジトリーのマスターブランチにあるテキストドキュメントには、 "latest and greatest" の変更と追加が含まれています。これらの変更には、Djangoの次期 feature release の対象となる新機能のドキュメントが含まれています。そのため、最近の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 のバージョンと同一のものであるか、十分に注意してください!

Table of Contents

  • 次のステップへ
    • ドキュメントの探し方
    • ドキュメントの構成
    • ドキュメントの更新の方針
    • ドキュメントの入手
      • Web 版
      • プレーンテキスト版
      • ローカルで HTML で読む
    • バージョンごとの違い

前のトピックへ

高度なチュートリアル: 再利用可能アプリの書き方

次のトピックへ

Django への初めてのパッチを書く

このページ

  • ソースコードを表示

クイック検索

Last update:

12月 02, 2019

« previous | up | next »