Django 文件流程¶

儘管 Django 的文件旨在以 HTML 格式在 https://django-docs.dev.org.tw/ 上閱讀，但為了獲得最大的彈性，我們會將其編輯為以 reStructuredText 標記語言撰寫的純文字檔案集合。

我們會從儲存庫的開發版本著手，因為它具有最新最好的文件，就像它具有最新最好的程式碼一樣。

我們也會將文件修復和改進向後移植到上次發布的分支，由合併者決定。這是因為讓上次發布的文件保持最新且正確是有利的（請參閱版本之間的差異）。

Django 的文件使用 Sphinx 文件系統，該系統又基於 docutils。基本概念是，輕度格式化的純文字文件會轉換為 HTML、PDF 和任何其他輸出格式。

Sphinx 包括一個 sphinx-build 命令，用於將 reStructuredText 轉換為其他格式，例如 HTML 和 PDF。此命令是可配置的，但 Django 文件包括一個 Makefile，它提供了一個更短的 make html 命令。

文件如何組織¶

文件分為幾個類別

• 教學課程 逐步引導讀者完成一系列步驟以創建某個事物。

  教學課程中重要的是幫助讀者實現有用的目標，最好是盡早實現，以便讓他們充滿信心。

  解釋我們正在解決的問題的本質，以便讀者了解我們試圖實現的目標。不要覺得您需要從解釋事物的運作方式開始 - 重要的是讀者做了什麼，而不是您解釋了什麼。回頭參考您所做的事情並在之後解釋可能會很有幫助。

• 主題指南 旨在較高層次上解釋概念或主題。

  連結到參考資料，而不是重複它。使用範例，不要不情願解釋對您來說似乎非常基本的事情 - 這可能是其他人需要的解釋。

  提供背景情境可以幫助新手將主題與他們已經知道的事情聯繫起來。

• 參考指南 包含 API 的技術參考。它們描述了 Django 內部機制的運作方式，並指導其使用。

  使參考資料緊緊專注於主題。假設讀者已經了解所涉及的基本概念，但需要知道或被提醒 Django 是如何做的。

  參考指南不是進行一般解釋的地方。如果您發現自己在解釋基本概念，您可能需要將該資料移至主題指南。

• 操作指南 是引導讀者完成關鍵主題步驟的食譜。

  操作指南中最重要的使用者的目標。操作指南應始終以結果為導向，而不是側重於 Django 如何實施所討論內容的內部細節。

  這些指南比教學課程更進階，並且假設使用者對 Django 的運作方式有一定的了解。假設讀者已完成教學課程，並且不要猶豫將讀者導回適當的教學課程，而不是重複相同的資料。

如何開始貢獻文件¶

$ git clone https://github.com/django/django.git

...\> git clone https://github.com/django/django.git

$ python -m venv .venv
$ source .venv/bin/activate
$ python -m pip install -r docs/requirements.txt

$ cd docs
$ make html

...\> cd docs
...\> make.bat html

寫作風格¶

當使用代名詞指稱假設的人，例如「具有工作階段 Cookie 的使用者」時，應使用性別中立的代名詞（他們/他們的/他們）。代替

• 他或她...使用他們。

• 他或她...使用他們。

• 他或她的...使用他們的。

• 他或她的...使用他們的。

• 他自己或她自己...使用他們自己。

盡量避免使用會盡量減少任務或操作難度的詞彙，例如「容易」、「簡單」、「僅」、「僅僅」、「簡單明瞭」等等。人們的體驗可能與您的期望不符，當他們發現某個步驟不像暗示的那樣「簡單明瞭」或「簡單」時，他們可能會感到沮喪。

常用術語¶

以下是一些關於整個文件中常用術語的樣式指南

• Django – 當指稱框架時，將 Django 大寫。它僅在 Python 程式碼和 djangoproject.com 標誌中為小寫。

• email – 無連字符號。

• HTTP – 預期的發音是「Aitch Tee Tee Pee」，因此前面應該接「an」而不是「a」。

• MySQL、PostgreSQL、SQLite

• SQL – 當提到 SQL 時，預期的發音應該是「Ess Queue Ell」，而不是「sequel」。因此在「Returns an SQL expression」這樣的詞組中，「SQL」前面應該接「an」而不是「a」。

• Python – 當指稱程式語言時，Python 的 P 應該大寫。

• realize、customize、initialize 等 – 使用美式英文的「ize」後綴，而非「ise」。

• subclass – 無連字符號的單一單字，無論是動詞（「subclass that model」）或名詞（「create a subclass」）皆是如此。

• the web、web framework – 不需大寫。

• website – 使用一個單字，不需大寫。

Django 特有術語¶

• model – 不需大寫。

• template – 不需大寫。

• URLconf – 使用三個大寫字母，"conf" 前面不加空格。

• view – 不需大寫。

reStructuredText 檔案指南¶

這些指南規範了我們的 reST (reStructuredText) 文件格式。

• 在章節標題中，僅需將首字及專有名詞大寫。

• 將文件寬度限制在 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」的連結。

• 所有的 Python 程式碼區塊都應該使用 blacken-docs 自動格式化工具進行格式化。如果設定了 pre-commit，這個工具將會被執行。

• 使用 intersphinx 來參考 Python 和 Sphinx 的文件。

• 在文字區塊中添加 .. code-block:: <lang> 以使其高亮顯示。建議優先使用 :: （兩個冒號）來自動高亮顯示。這樣做的好處是，如果程式碼包含某些無效的語法，它將不會被高亮顯示。例如，添加 .. code-block:: python 將強制高亮顯示，即使語法無效。

• 為了提高可讀性，請使用 .. admonition:: 描述性標題，而不是 .. note::。請謹慎使用這些方塊。

• 使用這些標題樣式

  ===
  One
  ===
  
  Two
  ===
  
  Three
  -----
  
  Four
  ~~~~
  
  Five
  ^^^^
  

• 使用 :rfc: 來參考 RFC，並盡可能連結到相關章節。例如，使用 :rfc:`2324#section-2.3.2` 或 :rfc:`自訂連結文字 <2324#section-2.3.2>`。

• 使用 :pep: 來參考 Python 增強提案（PEP），並盡可能連結到相關章節。例如，使用 :pep:`20#easter-egg` 或 :pep:`彩蛋 <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`（或省略 command_name 以用於所有命令共享的選項，例如 --verbosity）。

• 連結到 Trac 工單（通常保留用於修補程式發布說明）

  :ticket:`12345`
  

Django 的文件使用自訂的 console 指令來記錄涉及 django-admin、manage.py、python 等的命令列範例。在 HTML 文件中，它會呈現一個雙標籤 UI，一個標籤顯示 Unix 風格的命令提示符號，另一個標籤顯示 Windows 提示符號。

例如，你可以將這個片段

use this command:

.. code-block:: console

    $ python manage.py shell

替換成這個片段

use this command:

.. console::

    $ python manage.py shell

請注意兩件事

• 您通常會替換 .. code-block:: console 指令的出現次數。

• 您不需要更改程式碼範例的實際內容。您仍然假設是 Unix 環境（也就是 '$' 提示符號，'/' 作為檔案系統路徑元件分隔符號等）。

上面的範例將會呈現一個帶有兩個標籤的程式碼範例區塊。第一個標籤將會顯示

$ python manage.py shell

（與 .. code-block:: console 渲染的內容相同）。

第二個標籤將會顯示

...\> py manage.py shell

記錄新功能¶

我們對於新功能的政策是

所有新功能的說明文件都應該以清楚指定僅在 Django 開發版本中可用的功能的方式編寫。假設文件讀者使用的是最新的發行版本，而不是開發版本。

我們標記新功能的首選方法是在功能的說明文件前面加上：「.. versionadded:: X.Y」，接著是一個強制性的空白行和一個可選的描述（縮排）。

應該強調的一般改進或對 API 的其他變更，應使用「.. versionchanged:: X.Y」指令（格式與上面提到的 versionadded 相同）。

這些 versionadded 和 versionchanged 區塊應該是「獨立的」。換句話說，由於我們只保留這些註釋約兩個版本，因此能夠移除註釋及其內容，而無需重新排版、重新縮排或編輯周圍的文字是很方便的。例如，不要將新功能或變更功能的整個描述放在一個區塊中，而是像這樣做

.. 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 A.B 中的新功能：」和「Django A.B 中的變更：」。

如果新增了函式、屬性等，也可以像這樣使用 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", "john@example.com"), ("Mary", "mary@example.com")]
  
  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` 來參考它。

這基本上就是一切如何組合在一起的。

翻譯文件¶

如果你想協助將文件翻譯成其他語言，請參閱 本地化 Django 文件。

django-admin man page¶

Sphinx 可以為 django-admin 命令產生手冊頁。這是在 docs/conf.py 中設定的。與其他文件輸出不同，這個手冊頁應該包含在 Django 儲存庫和發布版本中，以 docs/man/django-admin.1 的形式存在。當更新文件時，不需要更新這個檔案，因為它會在發布過程中更新一次。

若要產生更新版本的手冊頁，請在 docs 目錄中執行 make man。新的手冊頁將會寫入 docs/_build/man/django-admin.1。