私たちはドキュメントの一貫性と読みやすさを重要視しています。結局のところ、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です！あなたのローカルマシンで変更がうまくいけば、 ウェブサイトでもうまくいくでしょう。
sphinx-autobuild can be used to automatically rebuild the documentation\nand reload the documentation page in the browser whenever a file changes. To\nenable auto-reloading:
\nInstall the package:
\nLinux / macOS
$ python -m pip install sphinx-autobuild\nWindows
...\\> py -m pip install sphinx-autobuild\nFrom the docs directory, run one of the following commands:
On Linux and macOS:
\n$ SPHINXBUILD=sphinx-autobuild SPHINXOPTS="--open-browser --delay 0" make html\nOn Windows (Command Prompt):
\n...\\> set SPHINXBUILD=sphinx-autobuild\n...\\> set SPHINXOPTS=--open-browser --delay 0\n...\\> make html\nOn Windows (PowerShell):
\nPS> $env:SPHINXBUILD="sphinx-autobuild"\nPS> $env:SPHINXOPTS="--open-browser --delay 0"\nPS> make html\nAlternatively, sphinx-autobuild can be invoked directly:
Linux / macOS
$ sphinx-autobuild . _build/html --open-browser --delay 0\nWindows
...\\> sphinx-autobuild . _build\\html --open-browser --delay 0\nThe auto-reloader can be stopped with Ctrl+C.
ソースファイルは docs/ ディレクトリにある .txt ファイルです。
これらのファイルはreStructuredTextマークアップ言語で書かれています。マークアップを学ぶには reStructuredText reference を参照してください。
\nこのページを編集するには、例えば docs/internals/contributing/writing-documentation.txt というファイルを編集し、 make html でHTMLを再構築します。
Several checks help maintain Django's documentation quality, including\nspelling,\ncode block formatting, and\ndocumentation style.
\nThese checks are run automatically in CI and must pass before documentation\nchanges can be merged. They can also be run locally with a single command:
\nLinux / macOS
$ make check\nWindows
...\\> make.bat check\nThis command runs all current checks and will include any new checks added in\nthe future.
\nBefore you commit your docs, it's a good idea to run the spelling checker.\nYou'll need to install sphinxcontrib-spelling first. The spell checker\nalso requires a system-level spell checking backend such as Aspell. Then from the docs directory, run:
Linux / macOS
$ make spelling\nWindows
...\\> make.bat spelling\nWrong words (if any) along with the file and line number where they occur will\nbe saved to _build/spelling/output.txt.
誤検出（実際には正しいのに検出されたエラー）が発生した場合は、以下のいずれかを行ってください:
\nSurround inline code or brand/technology names with double grave accents\n(``)
スペルチェッカーが認識する同義語を探します。
あなたが使っている単語が正しいと確信できる場合のみ、その単語を docs/spelling_wordlist に追加してください（リストはアルファベット順にしてください）。
All Python code blocks should be formatted using the blacken-docs\nauto-formatter. This is automatically run by the pre-commit hook if configured.
\nThe check can also be run manually: provided that blacken-docs is\ninstalled, run the following command from the docs directory:
Linux / macOS
$ make black\nWindows
...\\> make.bat black\nThe formatter will report any issues by printing them to the terminal and will\nreformat code blocks where possible.
\nDjango's documentation is checked for reStructuredText style and formal issues\nusing sphinx-lint. This helps catch problems like stray tabs, trailing\nwhitespace, excessive line length, and similar formatting problems.
\nOnce sphinx-lint is installed, the check can be run with the following\ncommand from the docs directory:
Linux / macOS
$ make lint\nWindows
...\\> make.bat lint\nThe command prints any violations to the terminal in the form\npath:line: message. If problems are encountered:
Read the message and fix the indicated issue (for example, remove trailing\nwhitespace, adjust backticks, or replace tabs with spaces).
For long lines consider wrapping text onto new lines or breaking long inline\nlinks into named references. The custom line length check should already skip\ncommon false positives such as headings, tables and long links.
Links in documentation can become broken or changed such that they are no\nlonger the canonical link. Sphinx provides a builder that can check whether the\nlinks in the documentation are working. From the docs directory, run:
Linux / macOS
$ make linkcheck\nWindows
...\\> make.bat linkcheck\nOutput is printed to the terminal, but can also be found in\n_build/linkcheck/output.txt and _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と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^^^^\nUse :rfc: to reference a Request for Comments (RFC) and\ntry to link to the relevant section if possible. For example, use\n:rfc:`2324#section-2.3.2` or\n: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:: を使って、その環境変数のドキュメントへの参照を定義する必要があるかもしれません。
Use :cve: to reference a Common Vulnerabilities and\nExposures (CVE) identifier. For example, use :cve:`2019-14232`.
When documenting Python objects (classes, methods, attributes, etc.) using\nSphinx directives such as .. class::, .. method::, and\n.. attribute::, all content must be properly indented to ensure correct\nrendering and to support features like automatic table of contents\ngeneration.
Follow these rules:
\nThe directive itself remains flush with the left margin (no indentation).
All descriptive text under the directive must be indented by 4 spaces.
Multi-line descriptions must keep the same indentation level.
Nested directives (for example, methods inside a class) require an\nadditional 4 spaces of indentation to maintain hierarchy.
Field lists (such as :param:, :returns:, etc.) must align with the\ndirective's content level.
Example:
\n.. class:: MyClass\n\n A brief description of the class.\n\n .. method:: my_method(arg1, arg2)\n\n Method description.\n\n :param arg1: Description of the first parameter\n :param arg2: Description of the second parameter\n\n .. attribute:: my_attribute\n\n Attribute description.\nSphinx'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's documentation uses a custom console directive for documenting\ncommand-line examples involving django-admin, manage.py, python,\netc. In the HTML documentation, it renders a two-tab UI, with one tab showing\na Unix-style command prompt and a second tab showing a Windows prompt.
例えば、次のような断片を:
\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" を付与し、必須の空白行とオプションの説明（インデントされたもの）を続けます。
General improvements or other changes to the APIs that should be emphasized\nshould use the ".. versionchanged:: X.Y" directive (with the same format\nas the versionadded mentioned above).
これらの 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 を使用してください:
Linux / macOS
$ 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"`\nWindows
...\\> 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...\nこれにより、以降のヘッダが ADMINS という設定の "正規の" ターゲットとしてマークアップされます。これは ADMINS について話すときはいつでも :setting:`ADMINS` を使って参照できることを意味します。
これが基本的な組み立て方です。
\nドキュメントを他の言語に翻訳したい場合は Django ドキュメントのローカライズ を参照してください。
\ndjango-admin の man ページLink to this heading#Sphinxは django-admin コマンドのマニュアルページを生成できます。これは docs/conf.py で設定します。他のドキュメントの出力とは異なり、このマニュアルページは docs/man/django-admin.1 として Django リポジトリやリリースに含める必要があります。ドキュメントを更新する際に、このファイルを更新する必要はありません。
To generate an updated version of the man page, in the docs directory, run:
Linux / macOS
$ make man\nWindows
...\\> make.bat man\nThe new man page will be written in docs/_build/man/django-admin.1.