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

Получение исходной документации¶

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

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

Начало работы с Sphinx¶

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

Чтобы собрать документацию локально, установите Sphinx:

$ python -m pip install Sphinx

...\> py -m pip install Sphinx

Затем из каталога docs создайте HTML:

$ make html

...\> make.bat html

Чтобы начать вносить свой вклад, вам нужно прочитать reStructuredText reference.

Your locally-built documentation will be themed differently than the documentation at docs.djangoproject.com. This is OK! If your changes look good on your local machine, they’ll look good on the website.

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

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

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

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

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

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

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

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

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

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

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

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

  Самое главное в руководстве how-to - это то, чего хочет добиться пользователь. How-to всегда должно быть ориентировано на результат, а не на внутренние детали того, как Django реализует то, о чем идет речь.

  Эти руководства являются более продвинутыми, чем учебники, и предполагают некоторые знания о том, как работает Django. Предполагается, что читатель изучил учебники, и не стесняйтесь отсылать его к соответствующему учебнику, а не повторять один и тот же материал.

Стиль написания¶

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

• он или она… используйте они.
• его или ее… используйте их.
• его или ее… использовать их.
• его или ее… используйте их.
• сам или сама… использовать себя.

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

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

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

• Django – при упоминании фреймворка пишите Django с большой буквы. Строчная буква используется только в коде Python и на логотипе djangoproject.com.
• email - без дефиса.
• MySQL, PostgreSQL, SQLite
• SQL – при упоминании SQL, ожидаемое произношение должно быть «Ess Queue Ell», а не «sequel». Таким образом, во фразе типа «Возвращает выражение SQL», «SQL» должно предшествовать «an», а не «a».
• Python – при упоминании языка пишите Python с большой буквы.
• realize, customize, initialize и т.д. – используйте американский суффикс «ize», а не «ise».
• subclass - это одно слово без дефиса, как в качестве глагола («подкласс этой модели»), так и в качестве существительного («создать подкласс»).
• Web, World Wide Web, the Web - обратите внимание, что Web всегда пишется с большой буквы, когда речь идет о Всемирной паутине.
• 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».

• Используйте 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>`.

• Используйте :rst<<<0 >>> для ссылки на предложение по улучшению Python (PEP) и старайтесь ссылаться на соответствующий раздел, если это возможно. Например, используйте :role:`:pep:<pep>`` или :pep:`20#easter-egg`.

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

• Используйте :rst<<<0 >>> для ссылки на переменную окружения. Вам также может понадобиться определить ссылку на документацию для этой переменной окружения, используя :rst<<<1 >>>.

Разметка, специфичная для 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"`

This is based on OptiPNG version 0.7.5. Older versions may complain about the -strip all option being 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 :rst<<<0 >>>, когда хотим сделать ссылку на другой документ в целом, и элемент :rst<<<1 >>>, когда хотим сделать ссылку на произвольное место в документе.

• Далее обратите внимание на то, как аннотированы настройки:

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

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

Проверка орфографии¶

Перед фиксацией документов рекомендуется запустить проверку орфографии. Сначала вам нужно установить sphinxcontrib-spelling. Затем из каталога docs запустите make spelling. Неправильные слова (если они есть) вместе с номером файла и строки, где они встречаются, будут сохранены в каталоге _build/spelling/output.txt.

Если вы столкнулись с ложными срабатываниями (вывод ошибок, которые на самом деле являются правильными), сделайте одно из следующих действий:

• Окружайте встроенный код или названия бренда/технологии подчеркиванием (`).
• Найдите синонимы, которые распознает программа проверки орфографии.
• Если, и только если вы уверены в правильности используемого слова - добавьте его в docs/spelling_wordlist (пожалуйста, сохраняйте список в алфавитном порядке).

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

Смотрите 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.