Написание документации¶

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

Хотя документация Django предназначена для чтения в формате HTML на сайте https://docs.djangoproject.com/, мы редактируем ее как набор обычных текстовых файлов, написанных на языке разметки reStructuredText для максимальной гибкости.

Мы работаем с версией репозитория для разработки, потому что в ней самая свежая и лучшая документация, так же как и самый свежий и лучший код.

Мы также бэкпортируем исправления и улучшения документации в последнюю ветку релиза по усмотрению разработчиков. Это связано с тем, что выгодно, чтобы документация по последнему релизу была актуальной и корректной (см. Различия между версиями).

Документация Django использует систему документации Sphinx, которая, в свою очередь, основана на docutils. Основная идея заключается в том, что слегка форматированная обычная текстовая документация преобразуется в HTML, PDF и любой другой выходной формат.

Sphinx включает команду sphinx-build для преобразования reStructuredText в другие форматы, например, HTML и PDF. Эта команда настраивается, но в документации Django есть Makefile, которая предоставляет более короткую команду make html.

Как организована документация¶

Документация разделена на несколько категорий:

• Tutorials провести читателя за руку через серию шагов по созданию чего-либо.

  Главное в учебнике - помочь читателю достичь чего-то полезного, желательно как можно раньше, чтобы придать ему уверенности.

  Объясните суть проблемы, которую мы решаем, чтобы читатель понял, чего мы пытаемся достичь. Не чувствуйте, что вам нужно начинать с объяснения того, как все работает - важно то, что делает читатель, а не то, что вы объясняете. Может быть полезно вернуться к тому, что вы уже сделали, и объяснить это после.

• Topic guides направлены на объяснение концепции или предмета на достаточно высоком уровне.

  Ссылайтесь на справочные материалы, а не повторяйте их. Используйте примеры и не отказывайтесь объяснять вещи, которые кажутся вам очень простыми - это может быть объяснение, которое нужно кому-то другому.

  Предоставление фонового контекста помогает новичкам связать тему с тем, что они уже знают.

• Reference guides содержат технические ссылки для API. Они описывают работу внутренних механизмов Django и инструктируют по их использованию.

  Держите справочный материал строго сфокусированным на теме. Предполагайте, что читатель уже понимает основные концепции, но ему необходимо узнать или напомнить, как это делает Django.

  Справочные руководства - не место для общих объяснений. Если вам приходится объяснять основные понятия, лучше перенести этот материал в тематическое руководство.

• How-to guides - это рецепты, которые проводят читателя через этапы изучения ключевых предметов.

  Самое главное в руководстве how-to - это то, чего хочет добиться пользователь. How-to всегда должно быть ориентировано на результат, а не на внутренние детали того, как 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». Таким образом, во фразе типа «Возвращает выражение SQL», «SQL» должно предшествовать «an», а не «a».
• Python – при упоминании языка пишите Python с большой буквы.
• realize, customize, initialize и т.д. – используйте американский суффикс «ize», а не «ise».
• subclass - это одно слово без дефиса, как в качестве глагола («подкласс этой модели»), так и в качестве существительного («создать подкласс»).
• веб, веб фреймворк - не пишется с большой буквы.
• website - используйте одно слово, без капитализации.

Специфическая терминология Django¶

• модель - не пишется с заглавной буквы.
• шаблон - не пишется с заглавной буквы.
• 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:: Descriptive title, а не .. note::. Используйте эти поля экономно.

• Используйте эти стили заголовков:

  ===
  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’s built-in markup, документация 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. Даже внутри блока это часто излишне, поскольку эти аннотации отображаются как «New in Django A.B:» и «Changed in 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 является lossy.

Пример¶

Для наглядного примера того, как все это сочетается, рассмотрим следующий гипотетический пример:

• Во-первых, документ 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`.

Вот, в принципе, и все.

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

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

django-admin man page¶

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

Чтобы создать обновленную версию man-страницы, запустите make man в каталоге docs. Новая man-страница будет записана в каталоге docs/_build/man/django-admin.1.