ドキュメントを書く

ドキュメントの一貫性と読みやすさを非常に重要視しています。結局のところ、Djangoはジャーナリズム環境で作成されました！したがって、ドキュメントはコードと同じように扱います。可能な限り頻繁にドキュメントを改善することを目指しています。

ドキュメントの変更には、通常、次の2つの形式があります。

一般的な改善：タイプミスの修正、エラーの修正、より明確な記述とより多くの例によるより良い説明。
新機能：前回のリリース以降にフレームワークに追加された機能のドキュメント。

このセクションでは、ライターがドキュメントの変更を最も便利でエラーが発生しにくい方法で作成する方法について説明します。

生のドキュメントを取得する

Djangoのドキュメントは https://docs.djangoproject.com/ でHTMLとして読むことを目的としていますが、最大限の柔軟性を実現するためにテキストファイルのコレクションとして編集しています。これらのファイルは、Djangoリリースのトップレベルのdocs/ディレクトリにあります。

ドキュメントへの貢献を開始したい場合は、ソースコードリポジトリからDjangoの開発バージョンを入手してください（開発バージョンのインストールを参照）。開発バージョンには、最新かつ最高のコードがあるのと同じように、最新かつ最高のドキュメントがあります。また、コミッターの裁量により、ドキュメントの修正と改善を最後のリリースブランチにバックポートします。これは、最後のリリースのドキュメントを最新かつ正確にすることが非常に有利であるためです（バージョン間の違いを参照）。

Sphinxの使用を開始する

Djangoのドキュメントは、 Sphinx ドキュメントシステムを使用しています。このシステムは、 docutils に基づいています。基本的な考え方は、簡単にフォーマットされたプレーンテキストのドキュメントをHTML、PDF、およびその他の出力フォーマットに変換することです。

ドキュメントをローカルでビルドするには、Sphinxをインストールします。

次に、docsディレクトリから、次のHTMLを作成します。

貢献を始めるには、 reStructuredTextリファレンスを読むことをお勧めします。

ローカルで作成されたドキュメントは、 docs.djangoproject.com のドキュメントとは異なるテーマになります。これはOKです！ローカルマシンで変更が適切に表示される場合は、Webサイトでも適切に表示されます。

ドキュメントの構成方法

ドキュメントはいくつかのカテゴリに分類されています。

チュートリアルは、読者に一連の手順を実行して、何かを作成します。

チュートリアルで重要なことは、読者に自信を与えるために、読者が何か役に立つことを、できればできるだけ早く達成できるようにすることです。

私たちが解決しようとしている問題の性質を説明して、読者が私たちが達成しようとしていることを理解できるようにします。物事がどのように機能するかについての説明から始める必要があるとは思わないでください。重要なのは、説明することではなく、読者が行うことです。あなたがしたことを振り返り、後で説明することは役に立つかもしれません。
トピックガイドは、概念または主題をかなり高いレベルで説明することを目的としています。

繰り返すのではなく、参考資料にリンクします。例を使用して、あなたにとって非常に基本的であると思われることを説明することを躊躇しないでください-それは他の誰かが必要とする説明かもしれません。

背景のコンテキストを提供することは、新参者がトピックを彼らがすでに知っていることに結び付けるのに役立ちます。
リファレンスガイドには、APIのテクニカルリファレンスが含まれています。それらは、Djangoの内部機械の機能を説明し、その使用法を指示します。

参考資料は、主題にしっかりと焦点を合わせてください。読者は関連する基本的な概念をすでに理解しているが、Djangoがそれをどのように行うかを知っているか思い出させる必要があると仮定します。

リファレンスガイドは、一般的な説明の場所ではありません。基本的な概念を説明していることに気付いた場合は、その資料をトピックガイドに移動することをお勧めします。
ハウツーガイドは、主要な主題の手順を読者に説明するレシピです。

ハウツーガイドで最も重要なのは、ユーザーが達成したいことです。ハウツーは、Djangoが議論されていることをどのように実装するかについての内部の詳細に焦点を合わせるのではなく、常に結果指向である必要があります。

これらのガイドはチュートリアルよりも高度であり、Djangoがどのように機能するかについてある程度の知識があることを前提としています。読者がチュートリアルに従っていると仮定し、同じ資料を繰り返すのではなく、読者を適切なチュートリアルに戻すことを躊躇しないでください。

文体

「セッションCookieを持つユーザー」など、架空の人物を参照して代名詞を使用する場合は、性別を問わない代名詞（彼ら/彼ら/彼ら）を使用する必要があります。それ以外の：

彼または彼女は…それらを使用します。
彼または彼女…それらを使用してください。
彼または彼女…彼らを使用してください。
彼または彼女の…彼らのものを使用してください。
自分自身…自分自身を使用します。

「簡単」、「単純」、「ただ」、「単に」、「簡単」など、タスクや操作に伴う困難を最小限に抑える言葉は使用しないようにしてください。人々の経験はあなたの期待と一致しないかもしれません、そして彼らがそれが暗示されるように「単純な」または「単純な」ステップを見つけないとき、彼らは欲求不満になるかもしれません。

一般的に使用される用語

ドキュメント全体で一般的に使用される用語に関するいくつかのスタイルガイドラインを次に示します。

Django –フレームワークを参照するときは、Djangoを大文字にします。 Pythonコードとdjangoproject.comロゴでのみ小文字になります。
email –ハイフンなし。
MySQL 、 PostgreSQL 、 SQLite
SQL – SQLを参照する場合、予想される発音は「続編」ではなく「EssQueueEll」である必要があります。したがって、「SQL式を返す」のようなフレーズでは、「SQL」の前に「a」ではなく「an」を付ける必要があります。
Python –言語を参照するときは、Pythonを大文字にします。
実現、カスタマイズ、初期化など。 –「ise」ではなく、アメリカの「ize」接尾辞を使用します。
subclass –動詞（「そのモデルのサブクラス」）と名詞（「サブクラスの作成」）の両方として、ハイフンのない単一の単語です。
Web 、 World Wide Web 、 Web – World Wide Webを参照する場合、Webは常に大文字で表記されます。
ウェブサイト –大文字を使わずに1つの単語を使用します。

Django固有の用語

model –大文字ではありません。
template –大文字ではありません。
URLconf –「conf」の前にスペースを入れずに3つの大文字を使用します。
ビュー –大文字ではありません。

reStructuredTextファイルのガイドライン

これらのガイドラインは、reST（reStructuredText）ドキュメントのフォーマットを規制しています。

セクションタイトルでは、最初の単語と固有名詞のみを大文字にします。
2行に分割した場合、または別の正当な理由でコード例が大幅に読みにくくならない限り、ドキュメントを80文字幅でラップします。
ドキュメントを作成および編集するときに覚えておくべき主なことは、セマンティックマークアップが多いほど適切に追加できるということです。そう：
```
Add ``django.contrib.auth`` to your ``INSTALLED_APPS``...
```
以下ほど役に立ちません：
```
Add :mod:`django.contrib.auth` to your :setting:`INSTALLED_APPS`...
```
これは、Sphinxが後者の適切なリンクを生成するためです。これは読者を大いに助けます。

ターゲットの前に~（チルダ）を付けると、そのパスの「最後のビット」のみを取得できます。したがって、:mod:`~django.contrib.auth`は「auth」というタイトルのリンクを表示します。
intersphinxを使用して、PythonおよびSphinxのドキュメントを参照してください。
.. code-block:: <lang>をリテラルブロックに追加して、それらが強調表示されるようにします。 ::（2つのコロン）を使用した自動強調表示に依存することをお勧めします。これには、コードに無効な構文が含まれている場合、強調表示されないという利点があります。たとえば、.. code-block:: pythonを追加すると、無効な構文にもかかわらず、強制的に強調表示されます。
読みやすさを向上させるには、.. note::ではなく.. admonition:: Descriptive titleを使用してください。これらのボックスは慎重に使用してください。

次の見出しスタイルを使用します。

===
One
===

Two
===

Three
-----

Four
~~~~

Five
^^^^

:rfc:を使用してRFCを参照し、可能であれば関連するセクションにリンクしてみてください。たとえば、:rfc:`2324#section-2.3.2`または:rfc:`Custom link text <2324#section-2.3.2>`を使用します。
:pep:を使用してPython拡張提案（PEP）を参照し、可能であれば関連するセクションにリンクしてみてください。たとえば、:pep:`20#easter-egg`または:pep:`Easter Egg <20#easter-egg>`を使用します。
コード例で値が引用されていない限り、:mimetype:を使用してMIMEタイプを参照します。
:envvar:を使用して、環境変数を参照します。 .. envvar::を使用して、その環境変数のドキュメントへの参照を定義する必要がある場合もあります。

Django固有のマークアップ

Sphinxの組み込みマークアップに加えて、Djangoのドキュメントはいくつかの追加の記述単位を定義しています。

設定：
```
.. 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:: migrate
```
リンクするには、:djadmin:`migrate`を使用します。
django-adminコマンドラインオプション：
```
.. django-admin-option:: --traceback
```
リンクするには、:option:`command_name --traceback`を使用します（または、--verbosityなどのすべてのコマンドで共有されるオプションのcommand_nameを省略します）。
Tracチケットへのリンク（通常はパッチリリースノート用に予約されています）：
```
:ticket:`12345`
```

Djangoのドキュメントでは、カスタムconsoleディレクティブを使用して、django-admin、manage.py、pythonなどのコマンドラインの例をドキュメント化しています。 HTMLドキュメントでは、2つのタブのUIがレンダリングされ、1つのタブにはUnixスタイルのコマンドプロンプトが表示され、もう1つのタブにはWindowsのプロンプトが表示されます。

たとえば、次のフラグメントを置き換えることができます。

use this command:

.. code-block:: console

    $ python manage.py shell

これで：

use this command:

.. console::

    $ python manage.py shell

2つのことに注意してください。

通常、.. code-block:: consoleディレクティブのオカレンスを置き換えます。
コード例の実際の内容を変更する必要はありません。あなたはまだUnix-y環境（すなわち '$'プロンプト記号、ファイルシステムパスコンポーネント区切り文字としての'/'など）

上記の例では、2つのタブを持つコード例ブロックをレンダリングします。最初のものは表示されます：

$ python manage.py shell

（.. code-block:: consoleがレンダリングしたものからの変更はありません）。

2番目のものは次のように表示されます。

...\> py manage.py shell

新機能の文書化

新機能に関するポリシーは次のとおりです。

新機能のすべてのドキュメントは、機能がDjango開発バージョンでのみ利用可能であることを明確に示す方法で作成する必要があります。ドキュメントリーダーが開発バージョンではなく最新リリースを使用していると仮定します。

新しい機能をマークするための推奨される方法は、機能のドキュメントの前に「.. versionadded:: X.Y」を付け、その後に必須の空白行とオプションの説明（インデント）を付けることです。

一般的な改善、または強調する必要のあるAPIのその他の変更では、「.. versionchanged:: X.Y」ディレクティブ（上記のversionaddedと同じ形式）を使用する必要があります。

これらのversionaddedおよびversionchangedブロックは、「自己完結型」である必要があります。つまり、これらの注釈は2つのリリースの間しか保持されないため、周囲のテキストをリフロー、再インデント、または編集することなく、注釈とその内容を削除できると便利です。たとえば、新しい機能または変更された機能の説明全体をブロックに入れる代わりに、次のようにします。

.. class:: Author(first_name, last_name, middle_name=None)

    A person who writes books.

    ``first_name`` is ...

    ...

    ``middle_name`` is ...

    .. versionchanged:: A.B

        The ``middle_name`` argument was added.

変更された注釈メモは、セクションの上部ではなく下部に配置します。

また、versionaddedまたはversionchangedブロックの外部で特定のバージョンのDjangoを参照することは避けてください。ブロック内であっても、これらのアノテーションはそれぞれ「Django ABの新機能」と「DjangoABの変更」としてレンダリングされるため、冗長になることがよくあります。

関数、属性などの場合。が追加されたら、次のようなversionaddedアノテーションを使用することもできます。

.. attribute:: Author.middle_name

    .. versionadded:: A.B

    An author's middle name.

.. versionadded:: A.Bアノテーションは、時が来てもインデントを変更せずに削除できます。

画像の最小化

可能な場合は画像圧縮を最適化します。 PNGファイルの場合は、OptiPNGとAdvanceCOMPのadvpngを使用します。

$ cd docs
$ optipng -o7 -zm1-9 -i0 -strip all `find . -type f -not -path "./_build/*" -name "*.png"`
$ advpng -z4 `find . -type f -not -path "./_build/*" -name "*.png"`

これは、OptiPNGバージョン0.7.5に基づいています。古いバージョンでは、-strip allオプションが不可逆であると文句を言う場合があります。

例

すべてがどのように組み合わされるかの簡単な例については、次の架空の例を検討してください。

まず、ref/settings.txtドキュメントの全体的なレイアウトは次のようになります。

========
Settings
========

...

.. _available-settings:

Available settings
==================

...

.. _deprecated-settings:

Deprecated settings
===================

...

次に、topics/settings.txtドキュメントには次のようなものが含まれている可能性があります。
```
You can access a :ref:`listing of all available settings
<available-settings>`. For a list of deprecated settings see
:ref:`deprecated-settings`.

You can find both in the :doc:`settings reference document
</ref/settings>`.
```
別のドキュメント全体にリンクする場合はSphinx doc相互参照要素を使用し、ドキュメント内の任意の場所にリンクする場合はref要素を使用します。

次に、設定に注釈が付けられていることに注目してください。

.. setting:: ADMINS

ADMINS
======

Default: ``[]`` (Empty list)

A list of all the people who get code error notifications. When
``DEBUG=False`` and a view raises an exception, Django will email these people
with the full exception information. Each member of the list should be a tuple
of (Full name, email address). Example::

    [('John', '[email protected]'), ('Mary', '[email protected]')]

Note that Django will email *all* of these people whenever an error happens.
See :doc:`/howto/error-reporting` for more information.

これにより、次のヘッダーが設定ADMINSの「正規」ターゲットとしてマークアップされます。つまり、ADMINSについて話すときはいつでも、:setting:`ADMINS`を使用して参照できます。

それが基本的にすべてが一緒に収まる方法です。

スペルチェック

ドキュメントをコミットする前に、スペルチェッカーを実行することをお勧めします。最初に sphinxcontrib-spelling をインストールする必要があります。次に、docsディレクトリからmake spellingを実行します。間違った単語（ある場合）は、それらが発生したファイルと行番号とともに_build/spelling/output.txtに保存されます。

誤検知（実際には正しいエラー出力）が発生した場合は、次のいずれかを実行します。

インラインコードまたはブランド/テクノロジー名をアクサングラーブ（ `）で囲みます。
スペルチェッカーが認識する同義語を見つけます。
使用している単語が正しいと確信できる場合に限り、docs/spelling_wordlistに追加してください（リストはアルファベット順に保持してください）。

ドキュメントの翻訳

ドキュメントを別の言語に翻訳したい場合は、 Djangoドキュメントのローカライズを参照してください。

django-adminのマニュアルページ

Sphinxは、 django-admin コマンドのマニュアルページを生成できます。これはdocs/conf.pyで構成されています。他のドキュメント出力とは異なり、このマニュアルページはdocs/man/django-admin.1としてDjangoリポジトリとリリースに含まれている必要があります。このファイルはリリースプロセスの一部として一度更新されるため、ドキュメントを更新するときにこのファイルを更新する必要はありません。

マニュアルページの更新バージョンを生成するには、docsディレクトリでmake manを実行します。新しいマニュアルページはdocs/_build/man/django-admin.1で記述されます。

ドキュメントの作成—Djangoドキュメント

目次