Написание документации ¶
Мы придаем большое значение последовательности и удобочитаемости документации. В конце концов, 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.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
Сворачивание изображений ¶
По возможности оптимизируйте сжатие изображений. Для файлов 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 man
docs
docs/_build/man/django-admin.1