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

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

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

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

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

Получение необработанной документации

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

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

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

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

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

$ python -m pip install Sphinx
... \> py -m pip install Sphinx

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

$ make html
... \> make.bat html

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

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

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

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

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

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

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

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

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

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

  • Справочные руководства содержат технические справочники по API. Они описывают функционирование внутреннего механизма Django и инструктируют его по использованию.

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

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

  • Практические руководства - это рецепты, которые проводят читателя через шаги по ключевым предметам.

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

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

Стиль письма

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

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

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

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

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

  • Django - при обращении к фреймворку используйте Django с заглавной буквы. Это строчные буквы только в коде Python и в логотипе djangoproject.com.
  • электронная почта - без дефиса.
  • MySQL , PostgreSQL , SQLite
  • SQL - при обращении к SQL ожидаемое произношение должно быть «Ess Queue Ell», а не «sequel». Таким образом, во фразе типа «Возвращает выражение SQL» перед словом «SQL» следует ставить «an», а не «a».
  • Python - при обращении к языку используйте Python с заглавной буквы.
  • реализовать , настроить , инициализировать и т. д. - используйте американский суффикс ize, а не ise.
  • подкласс - это отдельное слово без дефиса, как глагол («подкласс модели»), так и существительное («создать подкласс»).
  • Web , World Wide Web , Интернет - примечание, что Web всегда пишется с заглавной буквы при ссылке на World Wide Web.
  • сайт - используйте одно слово без заглавных букв.

Терминология, специфичная для Django

  • модель - это не заглавные буквы.
  • шаблон - он не пишется с заглавной буквы.
  • URLconf - используйте три заглавные буквы, без пробелов перед «conf».
  • вид - это не заглавные буквы.

Рекомендации для файлов 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 , в документации 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.Yversionadded

Эти 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 AB:» и «Изменено в Django AB» соответственно.

Если добавляется функция, атрибут и т. Д., Также можно использовать такую 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

Пример

Чтобы быстро понять, как все это сочетается, рассмотрим этот гипотетический пример:

  • Во-первых, 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>`.
    

    Мы используем docэлемент перекрестной ссылки Sphinx, когда мы хотим связать другой документ в целом, и 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', '[email protected]'), ('Mary', '[email protected]')]
    
    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(пожалуйста, храните список в алфавитном порядке).

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

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

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

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

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

Copyright ©2021 All rights reserved