私たちはドキュメントの一貫性と読みやすさを重要視しています。結局のところ、Django はジャーナリズムの環境で作られました！ですから、私たちはコードを扱うようにドキュメントを扱います。できるだけ頻繁に改善することを目指しています。
\nドキュメンテーションの変更には、一般的に2つの形式があります:
\n全般的な改善: 誤字脱字の修正、エラーの修正、より分かりやすい文章とより多くの例による説明の改善。
新機能: 前回のリリース以降にフレームワークに追加された機能のドキュメントです。
このセクションでは、ライターが最も有用でミスの少ない方法で文書の変更を行う方法について説明します。
\nDjango のドキュメントは、 https://docs.djangoproject.com/ で HTML として読まれることを想定していますが、柔軟性を最大にするために、 reStructuredText マークアップ言語で書かれたプレーンテキストファイルの集合として編集しています。
\n私たちは開発版のリポジトリで作業します。なぜなら、最新かつ最高のドキュメントがあり、最新かつ最高のコードがあるからです。
\nまた、マージャーの判断で、ドキュメントの修正や改良を最後のリリースブランチにバックポートします。これは、最終リリースのドキュメントが最新で正しい方が有利だからです (バージョンごとの違い を参照してください)。
\nDjango のドキュメンテーションは Sphinx ドキュメンテーションシステムを使っ ており、docutils をベースにしています。基本的な考え方は、軽く整形されたプレーンテキストのドキュメントを HTML や PDF などの出力形式に変換するというものです。
\nSphinxには sphinx-build コマンドがあり、 reStructuredText を他のフォーマット、例えば HTML や PDF に変換できます。このコマンドは設定可能ですが、Djangoのドキュメンテーションには Makefile があり、より短い make html コマンドを提供しています。
ドキュメントはいくつかのカテゴリーに分類されています:
\nチュートリアル は、何かを作るための一連のステップを読者に手取り足取り教えてくれます。
\nチュートリアルで重要なことは、読者に自信を持たせるために、できればできるだけ早い段階で、何か役に立つことを達成させることです。
\n解決しようとしている問題の性質を説明することで、読者がこれから達成しようとしていることを理解できるようにしてください。物事がどう機能するかについての説明から始める必要はありません。重要なのは読者が何をするかであり、あなたが説明する内容ではありません。行ったことを振り返り、その後で説明することは時に有用です。
\nトピックガイド は、概念や主題をかなり高いレベルで説明することを目的としています。
\n参考資料を繰り返すのではなく、リンクさせましょう。自分にとっては基本的なことでも、他の人には必要な説明かもしれません。
\n背景となる文脈を提供することで、初心者がトピックをすでに知っている事柄と結びつけることができます。
\nリファレンスガイド には API の技術的なリファレンスが含まれています。Django の内部的な仕組みや使い方を説明しています。
\n参考資料は主題にしっかりと焦点を絞ってください。読者はすでに基本的な概念を理解しているが、 Django がどのようにそれを行うかを知るか、思い出す必要があると仮定してください。
\nリファレンスガイドは、一般的な説明をする場所ではありません。基本的な概念を説明する場合は、その資料をトピックガイドに移すとよいでしょう。
\nHow-to ガイド は鍵となる主題に関して、いくつかのステップを踏んで説明しているレシピ集です。
\nハウツーガイドで最も重要なのは、ユーザが何を達成したいかです。ハウツーは常に、 Django が何をどのように実装しているかという内部的な詳細に焦点を当てるよりも、結果指向であるべきです。
\nこれらのガイドはチュートリアルよりも高度で、Django がどのように動作するかについて、ある程度の知識があることを前提としています。読者はチュートリアルに従ったことがあると仮定し、同じ内容を繰り返すのではなく、適切なチュートリアルに戻ることを躊躇しないでください。
\nドキュメントへの貢献を始めたい場合は、ソースコードリポジトリから Django の開発版を入手してください (開発バージョンをインストールする を参照してください):
\nLinux / macOS
$ git clone https://github.com/django/django.git\nWindows
...\\> git clone https://github.com/django/django.git\nこれらの変更を提出するつもりなら、代わりに Django リポジトリをフォークして、このフォークをクローンすると便利かもしれません。
\n仮想環境を作成してアクティブにし、依存関係をインストールします:
\n$ python -m venv .venv\n$ source .venv/bin/activate\n$ python -m pip install -r docs/requirements.txt\ndocs ディレクトリから HTML 出力をビルドできます:
Linux / macOS
$ cd docs\n$ make html\nWindows
...\\> cd docs\n...\\> make.bat html\nローカルにビルドされたドキュメントは _build/html/index.html にアクセスできるようになり、どのウェブブラウザでも閲覧できるようになりますが、 docs.djangoproject.com にあるドキュメントとは異なるテーマで表示されます。これはOKです！あなたのローカルマシンで変更がうまくいけば、 ウェブサイトでもうまくいくでしょう。
ソースファイルは docs/ ディレクトリにある .txt ファイルです。
これらのファイルはreStructuredTextマークアップ言語で書かれています。マークアップを学ぶには reStructuredText reference を参照してください。
\nこのページを編集するには、例えば docs/internals/contributing/writing-documentation.txt というファイルを編集し、 make html でHTMLを再構築します。
ドキュメントをコミットする前に、スペルチェッカーを実行することをお勧めします。まず sphinxcontrib-spelling をインストールする必要があります。そして、 docs ディレクトリから、 make spelling を実行してください。間違っている単語があれば、その単語が含まれるファイルと行番号が _build/spelling/output.txt に保存されます。
誤検出（実際には正しいのに検出されたエラー）が発生した場合は、以下のいずれかを行ってください:
\nインラインコードやブランド・技術名は、ダブルグレイブアクセント（``）で囲んでください。
スペルチェッカーが認識する同義語を探します。
あなたが使っている単語が正しいと確信できる場合のみ、その単語を docs/spelling_wordlist に追加してください（リストはアルファベット順にしてください）。
ドキュメントのリンクが壊れたり、正規のリンクでなくなったりすることがあります。Sphinxはドキュメントのリンクが機能しているかどうかをチェックするビルダーを提供しています。docsディレクトリから、 make linkcheck を実行してください。出力はターミナルに出力されますが、 _build/linkcheck/output.txt や _build/linkcheck/output.json にも出力されます。
ステータスが "working "のエントリーは問題ありませんが、"unchecked "または "ignored "のエントリーは、チェックできないか、設定の無視ルールにマッチしているため、スキップされています。
\nステータスが "broken" のエントリは修正する必要があります。 "redirected" のステータスを持つものは、正規の場所を指すように更新する必要があるかもしれません。例えば、スキームが http:// → https:// に変更された場合などです。場合によっては、"redirected" リンクを更新したくないこともあります。例えば、常にドキュメントの最新版や安定版を指すように書き換えたい場合などです。例えば、 /en/stable/ → /en/3.2/ のようにです。
"セッション・クッキーを持つユーザ" のような、仮想的な人物を指して代名詞を使うときは、下記のようなものの代わりに、性別に中立な代名詞(they/their/them)を使うべきです。:
\nhe や she... they を使います。
him や her... them を使います。
his や her... their を使います。
his や hers... theirs を使います。
himself や herself... themselves を使います。
「簡単に」、「単に」、「ただ」、「単に」、「単純に」など、作業や操作の難しさを最小化するような言葉はなるべく使わないようにしましょう。人々の経験とあなたの期待とは一致しないかもしれませんし、暗示されているような「簡単な」「単純な」ステップを見つけられなかったときに、不満を抱くかもしれません。
\nここでは、ドキュメントの中でよく使われる用語についてのスタイルガイドラインを示します:
\nDjango -- このフレームワークを指すときは、Django を大文字にします。Python のコードと djangoproject.com のロゴの中だけ小文字です。
email -- ハイフンなし。
HTTP -- 予想される発音は "Aitch Tee Tee Pee "なので、"a "ではなく "an "を前に置くべきです。
MySQL, PostgreSQL, SQLite
SQL -- SQLを指す場合、"sequel "ではなく、"Ess Queue Ell "と発音します。したがって、"Returns an SQL expression "のようなフレーズでは、"SQL "の前に "an "を付けるべきであり、"a "を付けるべきではありません。
Python -- 言語を指すときは、Pythonを大文字にします。
realize, customize, initialize など。接尾辞は "ise" ではなく、アメリカの "ize" を使います。
subclass -- 動詞（「そのモデルをサブクラス化する」）としても名詞（「サブクラスを作成する」）としても、ハイフンなしの1語です。
the web, web framework -- 大文字ではありません。
website -- 大文字にせず、1語にしてください。
model -- 大文字ではありません。
template -- 大文字ではありません。
URLconf -- "conf "の前にはスペースを入れず、大文字を3文字使います。
view -- 大文字ではありません。
このガイドラインは、reST（reStructuredText）文書の書式を規定しています:
\nセクションのタイトルでは、最初の単語と固有名詞のみ先頭を大文字にします。
コード例が2行に分割されると著しく読みにくくなる場合や、その他の正当な理由がある場合を除き、ドキュメントは80文字の幅で折り返します。
ドキュメントを書いたり編集したりするときに心に留めておくべきことは、セマンティックなマークアップは多ければ多いほど良いということです。よって:
\nAdd ``django.contrib.auth`` to your ``INSTALLED_APPS``...\nこのように書くより、次のように書くほうが役立ちます:
\nAdd :mod:`django.contrib.auth` to your :setting:`INSTALLED_APPS`...\nこれは、Sphinxが後者のために適切なリンクを生成してくれるからです。
\nターゲットの前に ~ (チルダ) を付けると、そのパスの「最後の部分」だけを取得できます。つまり、 :mod:`~django.contrib.auth` は "auth" というタイトルのリンクを表示します。
すべての Python コードブロックは blacken-docs の自動フォーマットを使ってフォーマットされるべきです。これは pre-commit が設定されていれば実行されます。
PythonとSphinxのドキュメントを参照するには、 intersphinx を使用してください。
リテラルブロックには .. code-block:: <lang> を追加して、ハイライトされるようにします。 :: （2つのコロン）を使用した自動ハイライトに頼るほうがいいでしょう。これには、コードに無効な構文が含まれていてハイライトされないような場合に利点があります。たとえば .. code-block:: python を追加すると、無効な構文があっても強制的にハイライトされます。
可読性を向上させるために、 .. note:: の代わりに .. admonition:: Descriptive title を使用してください。これらのボックスは控えめに使用してください。
これらの見出しスタイルを使用してください:
\n===\nOne\n===\n\nTwo\n===\n\nThree\n-----\n\nFour\n~~~~\n\nFive\n^^^^\nRFCを参照するには :rfc: を使い、可能であれば関連するセクションにリンクするようにしてください。例えば、 :rfc:`2324#section-2.3.2` や :rfc:`Custom link text <2324#section-2.3.2>` を使用します。
Python Enhancement Proposal (PEP) を参照するには :pep: を使い、可能であれば関連するセクションにリンクするようにしてください。例えば、 :pep:`20#easter-egg` や :pep:`Easter Egg <20#easter-egg>` を使います。
コードの例で値が引用符で囲まれていない限り、MIMEタイプを参照するには :mimetype: を使用します。
環境変数を参照するには :envvar: を使います。また、 .. envvar:: を使って、その環境変数のドキュメントへの参照を定義する必要があるかもしれません。
Sphinx's built-in markup 以外にも、Djangoドキュメントではいくつかの追加拡張を利用しています：
\n設定:
\n.. setting:: INSTALLED_APPS\n設定にリンクするには :setting:`INSTALLED_APPS` を使用します。
テンプレートタグ:
\n.. templatetag:: regroup\nリンクするには :ttag:`regroup` を使います。
テンプレートフィルタ:
\n.. templatefilter:: linebreaksbr\nリンクするには :tfilter:`linebreaksbr` を使います。
フィールドのルックアップ (例 Foo.objects.filter(bar__exact=whatever)):
.. fieldlookup:: exact\nリンクするには :lookup:`exact` を使います。
dango-admin コマンド:
.. django-admin:: migrate\nリンクするには :djadmin:`migrate` を使用します。
django-admin のコマンドラインオプション:
.. django-admin-option:: --traceback\nリンクするには、 :option:`command_name --traceback` を使います（ --verbosity のようなすべてのコマンドに共通するオプションの場合は command_name を省略することもできます）。
Trac チケットへのリンク (通常、パッチリリースノート用に予約されています):
\n:ticket:`12345`\nDjango のドキュメントでは、 djangoo-admin や manage.py, python などのコマンドラインの例をドキュメント化するために、カスタム の console ディレクティブを使っています。例）HTML ドキュメントでは、2 つのタブの UI を表示し、1 つのタブでは Unix スタイルのコマンドプロンプトを表示し、2 番目のタブでは Windows プロンプトを表示します。
例えば、次のような断片を:
\nuse this command:\n\n.. code-block:: console\n\n $ python manage.py shell\nこのように置き換えることができます:
\nuse this command:\n\n.. console::\n\n $ python manage.py shell\n下記の2点に注意してください:
\n通常、 .. code-block:: console ディレクティブの出現箇所を置き換えることになります。
コード例の実際の内容を変更する必要はありません。Unixライクな環境（つまり、 '$' というプロンプト記号、ファイルシステムパスコンポーネントの区切りとしての '/' など）を前提にしたまま記述します。
上の例では、2つのタブを持つコード例ブロックがレンダリングされます。最初のタブは:
\n$ python manage.py shell\n(.. code-block:: console がレンダリングするものと変わりません)。
２つめのタブは次のようになります:
\n...\\> py manage.py shell\n私たちの新機能に関するポリシーは以下のとおりです:
\n\n\n新機能のドキュメントはすべて、Django の開発版でしか利用できない機能を明確に指定するように書くべきです。ドキュメントの読者は開発版ではなく、最新のリリースを使っていると仮定してください。
\n
新機能をマークするには、その機能のドキュメントの前に ".. versionadded:: X.Y" を付与し、必須の空白行とオプションの説明（インデントされたもの）を続けます。
APIへの一般的な改善や強調すべきその他の変更には、 ".. versionchanged:: X.Y" ディレクティブを使用してください（上述の "versionadded" と同じフォーマットです）。
これらの versionadded と versionchanged ブロックは "自己完結型" であるべきです。言い換えると、これらの注釈は2つのリリースの間だけ残しておくために、周囲のテキストをリフローしたり、インデントを変更したり、編集したりすることなく、注釈とその内容を削除できればいいのです。例えば、新機能や変更された機能の説明全体をブロックに入れる代わりに、次のようにします:
.. class:: Author(first_name, last_name, middle_name=None)\n\n A person who writes books.\n\n ``first_name`` is ...\n\n ...\n\n ``middle_name`` is ...\n\n .. versionchanged:: A.B\n\n The ``middle_name`` argument was added.\nchanged 注釈ノートはセクションの上ではなく、一番下に配置します。
\nまた、 versionadded や versionchanged ブロックの外側で Django の特定のバージョンを参照するのは避けてください。ブロックの中であっても、これらのアノテーションはそれぞれ "New in Django A.B:" や "Changed in Django A.B" としてレンダリングされるので、そうするのは冗長な場合が多いです。
関数や属性などが追加された場合は、このように versionadded 注釈を使っても構いません:
.. attribute:: Author.middle_name\n\n .. versionadded:: A.B\n\n An author's middle name.\nこの .. versionadded:: A.B 注釈は、インデントを変更することなく削除できます。
可能な限り画像圧縮を最適化してください。 PNG ファイルの場合は、 OptiPNG と AdvanceCOMP の advpng を使用してください:
$ cd docs\n$ optipng -o7 -zm1-9 -i0 -strip all `find . -type f -not -path "./_build/*" -name "*.png"`\n$ advpng -z4 `find . -type f -not -path "./_build/*" -name "*.png"`\nこれは OptiPNG バージョン 0.7.5 に基づいています。古いバージョンは、-strip all オプションが非可逆であることに文句を言うかもしれません。
それぞれの例がどのように連携するのか、簡単な例を見てみましょう:
\nまず、 ref/settings.txt ドキュメント全体のレイアウトはこのようになっています:
========\nSettings\n========\n\n...\n\n.. _available-settings:\n\nAvailable settings\n==================\n\n...\n\n.. _deprecated-settings:\n\nDeprecated settings\n===================\n\n...\n次に、 topics/settings.txt ドキュメントには以下のような内容が含まれるかもしれません:
You can access a :ref:`listing of all available settings\n<available-settings>`. For a list of deprecated settings see\n:ref:`deprecated-settings`.\n\nYou can find both in the :doc:`settings reference document\n</ref/settings>`.\n別のドキュメント全体へのリンクを作成したい場合は Sphinx の doc クロスリファレンス要素を使用し、ドキュメント内の任意の場所へのリンクを作成したい場合は ref 要素を使用します。
次に、設定がどのようにアノテーションされているかに注目してください:
\n.. setting:: ADMINS\n\nADMINS\n======\n\nDefault: ``[]`` (Empty list)\n\nA list of all the people who get code error notifications. When\n``DEBUG=False`` and a view raises an exception, Django will email these people\nwith the full exception information. Each member of the list should be a tuple\nof (Full name, email address). Example::\n\n [("John", "john@example.com"), ("Mary", "mary@example.com")]\n\nNote that Django will email *all* of these people whenever an error happens.\nSee :doc:`/howto/error-reporting` for more information.\nこれにより、以降のヘッダが ADMINS という設定の "正規の" ターゲットとしてマークアップされます。これは ADMINS について話すときはいつでも :setting:`ADMINS` を使って参照できることを意味します。
これが基本的な組み立て方です。
\nドキュメントを他の言語に翻訳したい場合は Django ドキュメントのローカライズ を参照してください。
\ndango-admin の man ページLink to this heading#Sphinxは django-admin コマンドのマニュアルページを生成できます。これは docs/conf.py で設定します。他のドキュメントの出力とは異なり、このマニュアルページは docs/man/django-admin.1 として Django リポジトリやリリースに含める必要があります。ドキュメントを更新する際に、このファイルを更新する必要はありません。
最新版の man ページを作成するには、 docs ディレクトリで make man を実行してください。新しい man ページは docs/_build/man/django-admin.1 に作成されます。