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

Абзацы

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

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

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

Используйте уровни заголовков для создания разделов и позволяйте пользователям переходить непосредственно к конкретному разделу. Начинайте документы с # 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",
    ...
]
```

Ссылки

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

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

An [external link](https://wwww.example.com).
An [internal link to another document](/reference/contrib/legacy_richtext).
An auto generated link label to a page [](/getting_started/tutorial).
A [link to a reference](register_reports_menu_item).

(my_awesome_section)=

##### Some awesome section title

...

-   Auto generated label (preferred) [](my_awesome_section)
-   [label for section](my_awesome_section)

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

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

```{note}
Notes can provide complementary information.
```

```{warning}
Warnings can be scary.
```

Изображения

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

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

![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.coreutils

.. autofunction:: cautious_slugify
```

Таблицы

Используйте таблицы только при необходимости, используя синтаксис таблиц GitHub Flavored Markdown .

| Browser       | Device/OS |
| ------------- | --------- |
| Stock browser | Android   |
| IE            | Desktop   |
| Safari        | Windows   |

Оглавления

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

```{toctree}
---
maxdepth: 2
titlesonly:
---
getting_started/index
topics/index
```

```{contents}
---
local:
depth: 1
---
```

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

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

```{versionadded} 2.15
```

```{versionchanged} 2.15
```

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

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

<details>
    <summary>Supplementary information</summary>

    This will be visible when expanding the content.
</details>

Пример: