Getting the raw documentation¶

Though Django’s documentation is intended to be read as HTML at https://docs.djangoproject.com/, we edit it as a collection of text files for maximum flexibility. These files live in the top-level docs/ directory of a Django release.

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 committer, 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 Различия между версиями).

Getting started with Sphinx¶

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

To build the documentation locally, install Sphinx:

$ python -m pip install Sphinx

...\> py -m pip install Sphinx

Then from the docs directory, build the HTML:

$ make html

...\> make.bat html

To get started contributing, you’ll want to read the 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.

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

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

• Уроки ведут читателя за руку через серию шагов по работе с фреймворком.

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

  Explain the nature of the problem we’re solving, so that the reader understands what we’re trying to achieve. Don’t feel that you need to begin with explanations of how things work - what matters is what the reader does, not what you explain. It can be helpful to refer back to what you’ve done and explain afterwards.

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

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

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

• Reference guides contain technical reference for APIs. They describe the functioning of Django’s internal machinery and instruct in its use.

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

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

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

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

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

Стиль письма¶

When using pronouns in reference to a hypothetical person, such as «a user with a session cookie», gender neutral pronouns (they/their/them) should be used. Instead of:

• он или она… используйте они.

• его или ее… используйте их.

• его или ее… используйте их.

• его или ее… используйте их.

• сам или сама… использовать сами.

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

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

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

• Django — при упоминании фреймворка пишите Django с заглавной буквы. В коде Python и логотипе djangoproject.com оно пишется строчными буквами.

• email — без дефиса.

• MySQL, PostgreSQL, SQLite

• SQL — при упоминании SQL ожидаемое произношение должно быть «Эс Кью Эл», а не «сиквел». Таким образом, в такой фразе, как «Returns an SQL expression», «SQL» должно предшествовать «an», а не «a».

• Python — при упоминании языка пишите Python с большой буквы.

• realize, customize, initialize и т. д. – используйте американский суффикс «ize», а не «ise»

• подкласс — это одно слово без дефиса, как в качестве глагола («подкласс этой модели»), так и в качестве существительного («создать подкласс»).

• Web, World Wide Web, the Web – note Web is always capitalized when referring to the World Wide Web.

• website — используйте одно слово без заглавных букв.

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

• model — пишется со строчной буквы.

• template — пишется не с заглавной буквы.

• URLconf — используйте три заглавные буквы без пробела перед «conf.»

• view — пишется не с заглавной буквы.

Руководство по файлам reStructuredText¶

Это руководство определяет формат нашей reST (reStructuredText) документации:

• В заголовках разделов пишите с заглавной буквы только первые слова и имена собственные.

• Размещайте документацию по 80 символов в ширину, если только пример кода не стал значительно менее читабельным при разделении на две строки или по другой веской причине.

• The main thing to keep in mind as you write and edit docs is that the more semantic markup you can add the better. So:

  Add ``django.contrib.auth`` to your ``INSTALLED_APPS``...
  

  Isn’t nearly as helpful as:

  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::. Используйте эти поля экономно.

• Use these heading styles:

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

• Используйте :rfc: для ссылки на RFC и попытайтесь указать ссылку на соответствующий раздел, если это возможно. Например, используйте :rfc:`2324#section-2.3.2` или :rfc:`Пользовательский текст ссылки <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 определены некоторые дополнительные единицы описания:

• Settings:

  .. setting:: INSTALLED_APPS
  

  Чтобы создать ссылку на настройку, используйте :setting:`INSTALLED_APPS`.

• Template tags:

  .. templatetag:: regroup
  

  Для ссылки используйте :ttag:`regroup`.

• Template filters:

  .. templatefilter:: linebreaksbr
  

  Для ссылки используйте :tfilter:`linebreaksbr`.

• Field lookups (i.e. Foo.objects.filter(bar__exact=whatever)):

  .. fieldlookup:: exact
  

  Для ссылки используйте :lookup:`exact`.

• django-admin commands:

  .. django-admin:: migrate
  

  Для привязки используйте :djadmin:`migrate`.

• django-admin command-line options:

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

  Для ссылки используйте :option:`command_name --traceback` (или опустите command_name для параметров, общих для всех команд, например --verbosity).

• Links to Trac tickets (typically reserved for patch release notes):

  :ticket:`12345`
  

В документации Django используется специальная директива console для документирования примеров командной строки, включающих django-admin, manage.py, python, и т. д.). В HTML-документации отображается пользовательский интерфейс с двумя вкладкамина одной из вкладок которого отображается командная строка в стиле Unix, а на второй - командная строка Windows.

For example, you can replace this fragment:

use this command:

.. code-block:: console

    $ python manage.py shell

with this one:

use this command:

.. console::

    $ python manage.py shell

Обратите внимание на две вещи:

• Обычно вы заменяете вхождения директивы .. code-block:: console.

• Вам не нужно менять фактическое содержимое примера кода. Вы по-прежнему пишете его, предполагая среду Unix-y (т. е. символ приглашения '$', '/'` в качестве разделителя компонентов пути файловой системы и т. д.)

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

$ python manage.py shell

(Никаких изменений по сравнению с тем, что отобразил бы .. code-block:: console).

Второй покажет:

...\> py manage.py shell

Документирование новых функций¶

Наша политика в отношении новых функций:

All documentation of new features should be written in a way that clearly designates the features are only available in the Django development version. Assume documentation readers are using the latest release, not the development version.

Наш предпочтительный способ обозначения новых функций — добавление к документации функций предварительного текста: «.. versionadded:: X.Y», за которым следует обязательная пустая строка и необязательное описание (с отступом).

General improvements, or other changes to the APIs that should be emphasized should use the «.. versionchanged:: X.Y» directive (with the same format as the versionadded mentioned above.

These versionadded and versionchanged blocks should be «self-contained.» In other words, since we only keep these annotations around for two releases, it’s nice to be able to remove the annotation and its contents without having to reflow, reindent, or edit the surrounding text. For example, instead of putting the entire description of a new or changed feature in a block, do something like this:

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

If a function, attribute, etc. is added, it’s also okay to use a versionadded annotation like this:

.. attribute:: Author.middle_name

    .. versionadded:: A.B

    An author's middle name.

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

Минимизация изображений¶

Оптимизируйте сжатие изображений, где это возможно. Для файлов PNG используйте OptiPNG и AdvanceCOMP’s 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>`.
  

  We use the Sphinx doc cross reference element when we want to link to another document as a whole and the ref element when we want to link to an arbitrary location in a document.

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

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

  Это помечает следующий заголовок как «canonical» для настройки ADMINS. Это означает, что всякий раз, когда я говорю о ADMINS, я могу ссылаться на нее, используя :setting:`ADMINS`.

Вот так, в принципе, все и работает вместе.

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

Before you commit your docs, it’s a good idea to run the spelling checker. You’ll need to install sphinxcontrib-spelling first. Then from the docs directory, run make spelling. Wrong words (if any) along with the file and line number where they occur will be saved to _build/spelling/output.txt.

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

• Surround inline code or brand/technology names with grave accents (`).

• Найдите синонимы, распознаваемые средством проверки орфографии.

• Если и только если вы уверены, что слово, которое вы используете, правильное - добавьте его в 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.