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

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

Хотя документация 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 - при обращении к фреймворку всегда с большой буквы D. В коде Python и в логотипе djangoproject.com это только строчные буквы.
• электронная почта - без дефиса.
• MySQL , PostgreSQL , SQLite
• SQL - при обращении к SQL ожидается произношение «èsquiouèl», а не «sicouèl». Например, в таком предложении, как «Возвращает выражение SQL», «SQL» должно предшествовать «год», а не «а».
• Python - используйте заглавные буквы, когда это ссылка на язык.
• реализовать , настроить , инициализировать и т. д. - используйте американский суффикс «ize», а не «ise».
• подкласс - в слове без дефиса, будь то глагол («подкласс этой модели») или существительное («создать подкласс»).
• Интернет , World Wide 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` отображаться ссылка только на слово «авторизация».

• Используйте intersphinx для добавления ссылок на документацию Python и Sphinx.

• Добавьте литеральные блоки, чтобы выделить их синтаксис. Но в целом мы предпочитаем, чтобы автоматическая подсветка синтаксиса работала с помощью (два двоеточия). Преимущество заключается в том, что код, содержащий недопустимый синтаксис, не будет окрашен. Если, например, мы добавим , подсветка синтаксиса будет принудительной, даже если синтаксис не совсем верен... code-block:: <lang> :: .. code-block:: python

• Чтобы улучшить читаемость, используйте вместо . Используйте эти коробки экономно... admonition:: Titre descriptif .. note::

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

  ===
  One
  ===
  
  Two
  ===
  
  Three
  -----
  
  Four
  ~~~~
  
  Five
  ^^^^
  

• Используйте :rfc: для ссылки на RFC и попытайтесь указать ссылку на правильный раздел, если это возможно. Например, напишите :rfc:`2324#section-2.3.2` или .:rfc:`Texte de lien personnalisé <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=qqchose) ):

  .. fieldlookup:: exact
  

  Чтобы сделать ссылку, используйте :lookup:`exact` .

• Команды django-admin :

  .. django-admin:: migrate
  

  Чтобы сделать ссылку, используйте :djadmin:`migrate` .

• Параметры командной строки django-admin :

  .. django-admin-option:: --traceback
  

  Чтобы использовать ссылку (или опустить для параметров, общих для всех команд, например ).:option:`nom_commande --traceback` nom_commande --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-подобную среду (например, символ приглашения '$' , '/' разделитель путей к файловой системе и т. Д.)

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

$ 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 . Даже в блоке упоминание версий часто излишне, поскольку автоматический рендеринг этих аннотаций производит соответственно «Новое в Django AB» и «Изменено в Django AB».

Если функция, атрибут и т. Д. добавлен, также можно использовать аннотацию, versionadded подобную этой

.. attribute:: Author.middle_name

    .. versionadded:: A.B

    An author's middle name.

Мы можем удалить аннотацию без изменения отступа, когда придет время... versionadded:: A.B

Свернуть изображения ¶

По возможности оптимизируйте размер сжатия изображения, для файлов PBG используйте OptiPNG и advpng AdvanceCOMP:

$ 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"`

Этот пример основан на версии 0.7.5 OptiPNG. Более старые версии могут жаловаться, что опция теряет данные.--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>`.
  

  Мы используем элемент перекрестной ссылки 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', '[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 <https://pypi.org/project/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 man docs docs/_build/man/django-admin.1