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

Мы придаем большое значение последовательности и читабельности документации. В конце концов, Django был создан в журналистской среде! Поэтому мы относимся к документации так же, как и к коду: мы стремимся улучшать ее как можно чаще.

Изменения в документации обычно происходят в двух формах:

  • Общие улучшения: исправление опечаток, ошибок и улучшение объяснений за счет более четкого изложения и большего количества примеров.
  • Новые возможности: документация по возможностям, которые были добавлены в фреймворк с момента последнего выпуска.

В этом разделе объясняется, как писатели могут составлять изменения в документации наиболее полезными и наименее подверженными ошибкам способами.

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

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

If you’d like to start contributing to our docs, get the development version of Django from the source code repository (see Установка версии для разработки). The development version has the latest-and-greatest documentation, just as it has latest-and-greatest code. We also backport documentation fixes and improvements, at the discretion of the merger, to the last release branch. That’s because it’s highly advantageous to have the docs for the last release be up-to-date and correct (see Различия между версиями).

Начало работы с 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.

Ваша локально созданная документация будет оформлена иначе, чем документация по адресу docs.djangoproject.com. Это нормально! Если ваши изменения выглядят хорошо на вашей локальной машине, они будут хорошо выглядеть и на сайте.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

При использовании местоимений в отношении гипотетического лица, например, «пользователь с сессионным файлом 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».

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

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

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

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

JavaScript
Локализация Django
Вернуться на верх