Django ドキュメントの仕組み

revision-up-to:11321 (1.1)

... と、ドキュメント作業への貢献方法

Django のドキュメントは Sphinx ドキュメンテーションシステムを使っています。 Sphinx は docutils に基づいて作られています。 docutils は、簡単な書式の プレーンテキストを、 HTML や PDF その他の様々な出力形式で簡単に扱えるように することを念頭に置いて作られています。

ドキュメントを実際に手元でビルドするには、現状では Sphinx をインストールす る必要があります。インストールは easy_install Sphinx でできます。

さて、 html のビルドは簡単です。単に docs ディレクトリで make html を実行するだけです。

ドキュメント作業に貢献したいなら、まず ReStructuredText Primer を読みま しょう。その後 Sphinx 固有のマークアップ の説明を読んで、メタデータやイ ンデクス、相互参照の方法を学ぶとよいでしょう。

ドキュメントを書いたり編集したりする上で覚えておかねばならないのは、よりセ マンティックなマークアップを使う方がよい、ということです。従って:

Add ``django.contrib.auth`` to your ``INSTALLED_APPS``...

とするよりも:

Add :mod:`django.contrib.auth` to your :setting:`INSTALLED_APPS`...

と書いた方が便利なのです。なぜなら、後者のマークアップの場合、 Sphinx が適 切なリンクを生成するため、ドキュメントの読み手にとって非常に助かるからです。 制限はありません。可能な限り便利なマークアップを使ってください。

Django 固有のマークアップ

Sphinx の組み込みマークアップ の他に、Django ドキュメントではいくつか追 加で表記単位 (description unit) を定義しています:

  • 設定:

    .. setting:: INSTALLED_APPS

    リンクするには、 :setting:`INSTALLED_APPS` としてください。

  • テンプレートタグ:

    .. templatetag:: regroup

    タグの説明にリンクするには :ttag:`regroup` としてください。

  • テンプレートフィルタ:

    .. templatefilter:: linebreaksbr

    リンクするには :tfilter:`linebreaksbr` としてください。

  • フィールド照合 (Foo.objects.filter(bar__exact=whatever) など):

    .. fieldlookup:: exact

    リンクするには :lookup:`exact` としてください。

  • django-admin コマンド:

    .. django-admin:: syncdb

    リンクするには :djadmin:`syncdb` としてください。

  • django-admin コマンドラインオプション:

    .. django-admin-option:: --traceback

    リンクするには :djadminopt:`--traceback` としてください。

例

マークアップ方法を理解するために、以下の手順に従って確認してみましょう:

  • まず、 ref/settings.txt ドキュメントを見てみましょう。このドキュ メントは以下のような内容から始まっています:

    .. _ref-settings:

settings に設定できる値
==========================

...

  • topics/settings.txt ドキュメントを見ると、 ref/settings への リンクがどのように書かれているか分かります:

    利用可能な設定
==============

利用可能な設定は :ref:`setting リファレンス <ref-settings>` を参照
してください。

  • 設定項目をどのように表記しているかを見てみましょう:

    .. setting:: ADMIN_FOR

ADMIN_FOR
---------

デフォルト値: ``()`` (空のタプル)

admin 用サイトの設定モジュールで設定します。このサイトの admin を他
のサイトの admin にする場合、設定モジュールを (``'foo.bar.baz'`` の
形式のタプルで) 指定します。

admin サイトはこの変数を使って、モデルやビュー、テンプレートタグの
ドキュメントに対するイントロスペクションを自動的に行います。

    この .. settings:: の部分で、 ADMIN_FOR の「正しい」ターゲッ トとしてを定義しています。これで、 ADMIN_FOR について説明するとき に、 :setting:`ADMIN_FOR` を使って参照できます。

このようにして、お互いの参照を解決します。

TODO

ドキュメントの整備はほぼ終っていますが、まだ、ほぼ以降に挙げる順番にやらね ばならないことが残っています。

  • 「開発版で追加／変更された機能」の部分を、全て Sphinx の .. versionadded:: および .. versionchanged:: ディレクティブに 置き換えます。

  • おかしなリンクをチェックして修正します。 make linkcheck を実行し て、 300 個以上出るエラーや警告メッセージを全て修正します。

    特に、相対リンクを全て調べる必要があります。これらは正しい参照に変更 せねばなりません。

  • ほとんどの index.txt ドキュメントに、肝心の説明文が とても わず かしかないか、まったくありません。それぞれに、各階層下に収められてい るコンテンツのよい説明文が必要です。

  • 用語集がいい加減すぎます。もっと内容を濃くする必要があります。

  • メタデータターゲットをもっと増やします。まだ:

    ``File.close()``
~~~~~~~~~~~~~~~~

    のような部分がたくさんあり、以下のように書き直さねばなりません:

    .. method:: File.close()

    つまり、タイトルではなくメタデータを使わねばなりません。

  • リンクを追加します。現状のインラインコードリテラルは、ほぼ全て相互参 照に変更できます。

    _ext 以下にある literals_to_xrefs.py ファイルを参照してくださ い。このシェルスクリプトを使えば、作業が楽になります。

    おそらく終わりのない、地道な作業になるでしょう。

  • 適切な info フィールドリスト を追加する必要があります。

  • 色づけ表示の必要なリテラルブロックに .. code-block:: <lang> を付 加する必要があります。

ヒント

読みやすいドキュメントにするためのヒントをいくつか紹介しましょう:

  • 可能なかぎり、リンクを使いましょう。例えば、 ``ADMIN_FOR`` は :setting:`ADMIN_FOR` にしましょう。

  • ディレクティブの中には、プレフィクススタイルのもの (.. setting:: など)あります。プレフィクススタイルのディレクティブは、記述対象のブロッ クの 前 に置かねばなりません。その他 (.. class:: など) は独自の マークアップを生成します。その他のディレクティブは、記述対象のセクショ ンの中に置かねばなりません。こうしたディレクティブは「記述単位 (description unit)」と呼びます。

    どのディレクティブがどちらのタイプは、 _ext/djangodocs.py を 参照してください。このファイルの中で、それぞれのロールを登録していま す。

  • クラスや関数、モジュールなどを参照するときは、完全指定の名前 (:class:`django.contrib.contenttypes.models.ContentType`)を使うと よいでしょう。

    完全指定の名前を使っただけでは、出力はさほどきれいにならないでしょう。 というのも、オブジェクトの全てのパスが表示されてしまうからです。 ターゲットの先頭にチルダ (~) を付けると、パスの「最後の部分」だけ が表示されます。従って、 :class:`~django.contrib.contenttypes.models.ContentType` とすると、 単に “ContentType” と書かれたリンクを生成します。

« 前へ | 上へ | 次へ »