Руководящие принципы документации

• Рекомендации по форматированию
• Форматирование, которого следует избегать

Рекомендации по форматированию

Документация Wagtail использует смесь Markdown и reStructuredText. Мы рекомендуем сначала написать документацию в формате Markdown, и переходить к более продвинутому форматированию reStructuredText только в случае необходимости.

Ниже приведены форматы, которые мы рекомендуем использовать при написании документации для Wagtail.

Абзацы

Всё начинается здесь. Держите предложения короткими и разнообразными по длине.

Разделяйте текст пустой строкой, чтобы создать новый абзац.

Уровни заголовков

Используйте уровни заголовков для создания разделов и позволяйте пользователям напрямую переходить к определенному разделу. Начните документы с # h1, а затем переходите к ## h2 и дальнейшим подразделам, не пропуская уровни.

# Heading level 1

## Heading level 2

### Heading level 3

Списки

Используйте точки для неупорядоченных списков и цифры для упорядоченных списков. Предпочтительнее использовать тире - для маркеров. Гнёздите списки, отступая на 4 пробела.

- Bullet 1
- Bullet 2
    - Nested bullet 2
- Bullet 3

1. Numbered list 1
2. Numbered list 2
3. Numbered list 3

Стили встраивания

Используйте жирный шрифт и курсив экономно, встраивая code по мере необходимости.

Use **bold** and _italic_ sparingly, inline `code` when relevant.

Блоки кода

Убедитесь, что вы включили правильный код языка для подсветки синтаксиса и отформатировали код в соответствии с нашими рекомендациями по написанию кода. Часто используемые: python, css, html, html+django, javascript, console.

```python
INSTALLED_APPS = [
    ...
    "wagtail.core",
    ...
]
```

Ссылки

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

Не полагайтесь на links over code, так как их невозможно обнаружить.

An [external link](https://wwww.example.com).
An [internal link to another document](/reference/contrib/legacy_richtext.md).
A [link to a reference](register_reports_menu_item).

Ссылки на ссылки основаны на создании ссылки в reStructuredText. Предпочтительнее ссылаться на весь документ, если это возможно, в противном случае создайте ссылку, встроив reStructuredText с eval_rst:

```eval_rst
.. _register_reports_menu_item:
```

Примечания и предупреждения

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

```eval_rst note:: Notes can provide complementary information.
```

```eval_rst warning:: Warnings can be scary.
```

Изображения

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

• Все изображения должны иметь осмысленный alt текст, если они не являются декоративными.
• Изображения передаются как есть — выберите правильный формат и без потерь сжимайте все изображения.
• Используйте абсолютные пути к файлам изображений, чтобы они были более портативными.

![Screenshot of the workflow editing interface, with fields to change the workflow name, tasks, and assigned pages](/_static/images/screen44_workflow_edit.png)

Autodoc

С помощью функции autodoc Sphinx поддерживает написание документации в строках документации Python для последующей интеграции в страницы документации проекта. Это очень мощная функция, которую мы настоятельно рекомендуем использовать для документирования API Wagtail.

```eval_rst
.. module:: wagtail.core.utils

.. autofunction:: cautious_slugify
```

Таблицы

Используйте таблицы только по необходимости, с использованием простого синтаксиса reStructuredText, который достаточно сложно отформатировать.

```eval_rst
=============  =============
Browser        Device/OS    
=============  =============
Stock browser  Android      
IE             Desktop      
Safari         Windows      
=============  =============
```

Содержание

toctree и contents могут использоваться как вставки reStructuredText.

```eval_rst
.. toctree::
    :maxdepth: 2
    :titlesonly:

    getting_started/index
    topics/index
```

```eval_rst
.. contents::
```

Добавления, изменения, устаревшие функции

Sphinx предоставляет директивы метаданных выпуска для генерации этой информации последовательно. Используйте по мере необходимости.

```eval_rst
.. versionadded:: 2.15
```

```eval_rst
.. versionchanged:: 2.15
```

Постепенное раскрытие

Мы можем добавить дополнительную информацию в документацию с помощью HTML-элемента <details>. Это основано на синтаксисе HTML, который может быть трудно согласованно оформлять, поэтому старайтесь свести к минимуму этот тип форматирования.

<details>

<summary>Supplementary information</summary>

This will be visible when expanding the content.

</details>

Пример:

Форматирование, которого следует избегать

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

Вызовы

Мы используем только вызовы note:: и warning::. Избегайте important::, topic::, и tip::. Если вы найдете один из них, замените его на note::.

Глоссарий

Глоссарии Sphinx (.. glossary::) генерируют списки определений. Вместо этого используйте обычные списки с маркерами или цифрами, разделы с заголовками или таблицу.

Комментарии

Избегайте комментариев к документации в коммитах.

Рисунок

Рисунки reStructuredText (.. figure::) предлагают только незначительное улучшение по сравнению с обычными изображениями. Если ваш рисунок имеет подпись, добавьте её в виде абзаца с курсивом под изображением.

Другой синтаксис reStructuredText и директивы Sphinx

В целом, мы предпочитаем Markdown над reStructuredText, чтобы сделать создание документации для Wagtail максимально простым для новичков. Всегда отдавайте предпочтение Markdown, если форматирование документа сильно зависит от синтаксиса reStructuredText.

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

Произвольный HTML

Хотя наше инструментарий документации поддерживает встраивание произвольного HTML, это не приветствуется. Делайте это только в случае необходимости и если форматирование вряд ли потребует обновлений.