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

Абзацы

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

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

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

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

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

INSTALLED_APPS = [
    ...
    "wagtail",
    ...
]

```sh
# some comment
some command
```

# some comment
some command

```doscon
# some comment
some command
```

# some comment
some command

Ссылки

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

Не полагайтесь на 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.
```

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

```{note} Title's here will not work correctly
Notes can provide complementary information.
```

Изображения

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

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

![The TableBlock component in StreamField, with row header, column header, caption fields - and then the editable table](/_static/images/screen40_table_block.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>

Пример: