Процесс документирования Django¶

Хотя документация Django предназначена для чтения в формате HTML на https://docs.djangoproject.com/, мы редактируем ее как набор простых текстовых файлов, написанных на языке разметки 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

$ make check

...\> make.bat check

$ make spelling

...\> make.bat spelling

$ make black

...\> make.bat black

$ make lint

...\> make.bat lint

$ make linkcheck

...\> make.bat linkcheck

Стиль письма¶

При использовании местоимений в отношении гипотетического лица, например, «пользовательс сеансовым cookie», следует использовать гендерно-нейтральные местоимения (они/их). Вместо:

• он или она… используйте они.

• его или ее… используйте их.

• его или ее… используйте их.

• его или ее… используйте их.

• сам или сама… использовать сами.

Старайтесь избегать использования слов, которые преуменьшают сложность задачи или операции, таких как «легко», «просто», и т. д. Опыт людей может не соответствовать вашим ожиданиям, и они могут расстроиться, если не найдут шаг таким «простым» или «прямым», как предполагается.

Часто используемые термины¶

Вот некоторые рекомендации по стилю для терминов, часто используемых в документации:

• Django — при упоминании фреймворка пишите Django с заглавной буквы. В коде Python и логотипе djangoproject.com оно пишется строчными буквами.

• email — без дефиса.

• HTTP — ожидаемое произношение — «Эйч Ти Ти Пи» и поэтому ему должно предшествовать «an», а не «a».

• MySQL, PostgreSQL, SQLite

• SQL — при упоминании SQL ожидаемое произношение должно быть «Эс Кью Эл», а не «сиквел». Таким образом, в такой фразе, как «Returns an SQL expression», «SQL» должно предшествовать «an», а не «a».

• Python — при упоминании языка пишите Python с большой буквы.

• realize, customize, initialize и т. д. – используйте американский суффикс «ize», а не «ise»

• подкласс — это одно слово без дефиса, как в качестве глагола («подкласс этой модели»), так и в качестве существительного («создать подкласс»).

• 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».

• Используйте intersphinx для ссылки на документацию Python и Sphinx.

• Добавьте .. code-block:: <lang> к буквенным блокам, чтобы они выделились. Предпочитайте автоматическую подсветку с помощью :: (два двоеточия). Это имеет то преимущество, что если код содержит недопустимый синтаксис, он не будет выделен. Добавление .. code-block:: python, например, приведет к принудительному выделению, несмотря на недопустимый синтаксис.

• Для улучшения читабельности используйте .. admonition:: Descriptive title вместо .. 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:`Easter Egg <20#easter-egg>`.

• Используйте :mimetype: для ссылки на тип MIME, если только значение не заключено в кавычки для примера кода.

• Используйте :envvar: для ссылки на переменную среды. Вам также может потребоваться определить ссылку на документацию для этой переменной среды с помощью .. envvar::.

• Используйте :cve: для ссылки на идентификатор общих уязвимостей и уязвимостей (CVE). Например, используйте :cve:`2019-14232`.

• При документировании объектов Python (классов, методов, атрибутов и т. д.) с использованием `` директив Sphinx`__, таких как .. class::, .. метод:: и .. атрибут::, весь контент должен иметь правильные отступы, чтобы обеспечить правильное отображение и поддерживать такие функции, как автоматическое создание оглавления.

  Следуйте этим правилам:

  • Сама директива остается на одном уровне с левым полем (без отступов).

  • Весь описательный текст директивы должен иметь отступ в 4 пробела.

  • Многострочные описания должны иметь одинаковый уровень отступов.

  • Вложенные директивы (например, методы внутри класса) требуют дополнительных 4 пробелов отступа для поддержания иерархии.

  • Списки полей (такие как :param:, :returns: и т. д.) должны соответствовать уровню содержимого директивы.

  Пример:

  .. class:: MyClass
  
      A brief description of the class.
  
      .. method:: my_method(arg1, arg2)
  
          Method description.
  
          :param arg1: Description of the first parameter
          :param arg2: Description of the second parameter
  
      .. attribute:: my_attribute
  
          Attribute description.
  

Специфическая для 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-документации отображается пользовательский интерфейс с двумя вкладкамина одной из вкладок которого отображается командная строка в стиле Unix, а на второй - командная строка Windows.

Например, вы можете заменить этот фрагмент:

use this command:

.. code-block:: console

    $ python manage.py shell

этим:

use this command:

.. console::

    $ python manage.py shell

Обратите внимание на две вещи:

• Обычно вы заменяете вхождения директивы .. code-block:: console.

• Вам не нужно менять фактическое содержимое примера кода. Вы по-прежнему пишете его, предполагая среду Unix-y (т. е. символ приглашения '$', '/'` в качестве разделителя компонентов пути файловой системы и т. д.)

Пример выше отобразит блок примера кода с двумя вкладками. Первая покажет:

$ 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.

Размещайте измененные аннотации в нижней части раздела, а не в верхней.

Кроме того, избегайте ссылок на конкретную версию Django вне блока versionadded или versionchanged. Даже внутри блока это часто излишне, поскольку эти аннотации отображаются как «Новое в 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’s 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"`

...\> 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...
  

  Это помечает следующий заголовок как «canonical» для настройки ADMINS. Это означает, что всякий раз, когда я говорю о ADMINS, я могу ссылаться на нее, используя :setting:`ADMINS`.

Вот так, в принципе, все и работает вместе.

Перевод документации¶

См. Локализация документации Django если вы хотите помочь перевести документацию на другой язык.

Страница руководства django-admin¶

Sphinx может генерировать страницу руководства для команды django-admin. Это настраивается в docs/conf.py. В отличие от других выходных данных документации, эта страница руководства должна быть включена в репозиторий Django и релизы как docs/man/django-admin.1. Нет необходимости обновлять этот файл при обновлении документации, так как он обновляется один раз в процессе релиза.

Чтобы создать обновленную версию man-страницы, в каталоге docs запустите:

$ make man

...\> make.bat man

Новая страница руководства будет записана в docs/_build/man/django-admin.1.