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

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

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

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

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

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

Как начать вносить свой вклад в разработку документации

Клонируйте репозиторий Django на вашу локальную машину

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

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

Если вы планируете вносить эти изменения, возможно, вам будет полезно сделать форк репозитория Django и клонировать этот форк вместо него.

Настройка виртуальной среды и установка зависимостей

Создайте и активируйте виртуальную среду, а затем установите все необходимые компоненты:

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

Создайте документацию локально

Мы можем создать HTML-вывод из каталога docs:

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

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

Внесение правок в документацию

Исходными файлами являются файлы .txt, расположенные в каталоге docs/.

Эти файлы написаны на языке разметки reStructuredText. Для изучения разметки см. раздел reStructuredText reference.

Чтобы отредактировать эту страницу, например, мы отредактируем файл docs/internals/contributing/writing-documentation.txt и перестроим HTML с помощью make html.

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

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

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

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

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

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

Changed in Django 4.2:

Все блоки кода на языке Python в документации по Django были переформатированы с помощью blacken-docs.

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

Вернуться на верх