Синтаксис разметки reStructuredText

Базовые концепции

Синтаксис reStructuredText опирается на следующие концепции:

Отступы и пробелы имеют значение для команд разметки, но не имеют значения внутри текста (10 пробелов будут отображены как один).

Примечание

Не важно как делается отступ — пробелами или клавишей Tab, главное, чтобы они были одинакового размера.

В командах (директивах) используется символ обратной кавычки `, который располагается на клавише с буквой ё и символом ~

Заголовки

Примечание

Длина подчеркивания должна быть равна длине заголовка!

Заголовок 1 уровня
==================

Заголовок 2 уровня
------------------

Заголовок 3 уровня
~~~~~~~~~~~~~~~~~~

Заголовок 4 уровня
^^^^^^^^^^^^^^^^^^

Заголовок 5 уровня
##################

Внимание

Рекомендуется не использовать заголовки ниже 4 уровня.

Выделение текста

**жирный текст**

*курсив текст*

Выделение текста красным цветом, например, вот так: красный цвет, выполняется двумя обратными кавычками

``красный цвет``

Такое выделение следует использовать при написании имени модуля, файла, папки, параметра, запроса, порта и т.д.

Нумерованные списки

Для нумерованных списков следует использовать символ #.

#. Один
#. Два
#. Три

или

1. Один
2. Два
3. Три

Результат:

Один
Два
Три

Сложные нумерованные списки:

Для того чтобы нумерованный список продолжился нужно поставить пробел(см. пример)!

#. Текст первого пункта
#. Текст второго пункта
#. Этот пункт нам надо разбить еще на два пункта:

        #. подпункт номер один
        #. подпункт номер два
#. Текст четвертого пункта

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

Продолжаем наш текст

Результат:

Текст первого пункта
Текст второго пункта
Этот пункт нам надо разбить еще на два пункта:
1. подпункт номер один
2. подпункт номер два
Текст четвертого пункта
- это маркированный список четвертого пункта
- здесь сделаем второй пункт

А здесь продолжим наш текст новым абзацем…

Маркированные списки

Для маркированных списков следует использовать символ * или *.

* Один
* Два
* Три

Результат:

Один
Два
Три

Вложенные списки

* Первый уровень
  * Второй уровень
    * Третий уровень

Результат:

Первый уровень

Второй уровень

Третий уровень

Изображения

Вставка изображения

Для вставки изображения используйте следующий код:

.. _fig1:
.. figure:: img/insert_image.png
        :align: center
        :alt: Вставка изображения (альтернативный текст для html)

        Вставка изображения (подрисуночная подпись)

Результат:

Вставка изображения в тексте

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

Пример кода:

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

.. |обновление| image:: img/image_in_text.png

Вставка ссылки на изображение

Для вставки ссылки на изображение используйте ссылку на якорь вида :numref:`fig1`. Например, чтобы сослаться на изображение выше, сделайте следующие:

Это просто текст, но сейчас мы в нем сделаем ссылку на  :numref:`fig1`:

Результат:

Это просто текст, но сейчас мы в нем сделаем ссылку на fig1:

Ссылки и сноски

Внешние ссылки

Пример кода для вставки внешней ссылки:

Вот здесь расположена `ссылка на сайт IT-ONE <URL>`_

Результат:

Вот здесь расположена ссылка на сайт IT-ONE

Перекресные ссылки

Есть два способа вставки перекресных ссылок.

Способ 1 (простой)

В тексте можно просто указать название раздела, на который вы планируете поставить ссылку, например:

Здесь мы сделаем ссылку на раздел `Ссылки и сноски`_

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

Результат:

Здесь мы сделаем ссылку на раздел Ссылки и сноски

Внимание

При изменении названия раздела ссылка станет неактивной.

Способ 2 (с использованием ``якоря``)

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

Установить якорь вида: .._name_chapter: перед разделом, на который будет вести ссылка. Между якорем и заголовком должна быть пустая строка (см. рис. ниже).

Вставка якоря перед заголовком
Установить в нужное место текста ссылку ввида :ref:`name_chapter`

Пример кода:

Здесь мы сделаем ссылку на раздел выше :ref:`link`

Результат:

Здесь мы сделаем ссылку на раздел выше Ссылки и сноски

Способ 3 (внутренние ссылки)

В этом способе

Внутренние ссылки делаются так: ссылка_на_примечание_

Далее, в тексте вставляем в нужное место ``.. _ссылка_на_примечание:``,
в нашем примере мы установили ссылку над блоком "Примечание", в разделе "Таблицы".

Проверим результат:

Внутренние ссылки делаются так: ссылка_на_примечание

Ссылки на файлы (текстовые и для загрузки)

Допустим, есть структура документации:

> a
>> a_foo
>>> a_bar
> b
>> b_foo
> c

Для ссылки из любого места:

:doc:`link to a </a>
:doc:`link to a_foo </a/a_foo>`

из a
:doc:`relative link to a_foo <./a/foo>`

Cноски

Рекомендуется использовать сноски с автоматической нумерацией. При этом сноски старайтесь располагать рядом с текстом, в котором они используются.

Сноски с автоматической [#]_ нумерацией [#]_.

.. [#] Это первая сноска.
.. [#] Это вторая сноска.

Результат:

Сноски с автоматической [1] нумерацией [2].

Таблицы

Работа с таблицами

Есть несколько способов сделать таблицы.

.. table:: Заголовок таблицы (Внимание! Отступ таблицы относительно
                команды ..``table::`` обязателен)

        +------------------------+------------+----------+----------+
        | Header row, column 1   | Header 2   | Header 3 | Header 4 |
        | (header rows optional) |            |          |          |
        +========================+============+==========+==========+
        | body row 1, column 1   | column 2   | column 3 | column 4 |
        +------------------------+------------+----------+----------+
        | body row 2             | Cells may span columns.          |
        +------------------------+------------+---------------------+
        | body row 3             | Cells may  | - Table cells       |
        +------------------------+ span rows. | - contain           |
        | body row 4             |            | - body elements.    |
        +------------------------+------------+---------------------+

Примечание

Отступ таблицы относительно команды .. table:: обязателен

Результат:

Заголовок таблицы (Внимание! Отступ таблицы относительно команды ..``table::`` обязателен)
Header row, column 1 (header rows optional)	Header 2	Header 3	Header 4
body row 1, column 1	column 2	column 3	column 4
body row 2	Cells may span columns.
body row 3	Cells may span rows.	Table cells contain body elements.
body row 4	Cells may span rows.	Table cells contain body elements.

Простая таблица

.. table:: Простая таблица со сложной шапкой

        =====  =====  ======
        Inputs     Output
        ------------  ------
        A      B    A or B
        =====  =====  ======
        False  False  False
        True   False  True
        False  True   True
        True   True   True
        =====  =====  ======

Результат:

Простая таблица со сложной шапкой
Inputs		Output
A	B	A or B
False	False	False
True	False	True
False	True	True
True	True	True

CSV-таблица
Treat	Quantity	Description
Albatross	2.99	On a stick!
Crunchy Frog	1.49	If we took the bones out, it wouldn’t be crunchy, now would it?
Gannet Ripple	1.99	On a stick!

Результат:

CSV-таблица
Treat	Quantity	Description
Albatross	2.99	On a stick!
Crunchy Frog	1.49	If we took the bones out, it wouldn’t be crunchy, now would it?
Gannet Ripple	1.99	On a stick!

Вставка ссылки на таблицу

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

Установите перед таблицей якорь (см. рис. ниже).

Вставка якоря перед заголовком таблицы
В тексте установите ссылку на якорь вида вида :numref:`tab_example`

Внимание

После названия таблицы должна быть пустая строка и таблица должна иметь отступ от левого края (клавиша TAB для всей таблицы).

Например, чтобы сослаться на таблицу выше, используйте следующий код:

Посмотрите как можно перейти вот на эту таблицу (см. :numref:`tab_example`)

Результат:

Посмотрите как можно перейти вот на эту таблицу (см. tab_example)

Примечание

В названии якоря используйте префикс tab

Еще один пример:

Для работы с Программой сотрудник (программист) должен обладать
компетенциями, перечисленными в таблице (см. :numref:`tab_personal_example`) в том объеме,
который требуется для выполнения поставленных перед ним производственных
задач.

.. _tab_personal_example:

.. table:: Требования к персоналу (пример)

        +----+------------------------+-------------------------------+
        | №  | Компетенция            | Уровень                       |
        +====+========================+===============================+
        | 1  | Знакомство со СМЭВ 3   | В объеме, изложенном в        |
        |    |                        | инструкциях, технологических  |
        |    |                        | стандартах, методических      |
        |    |                        | рекомендаций, регламентах и   |
        |    |                        | руководствах, приведенных на  |
        |    |                        | сайте                         |
        |    |                        | https                         |
        |    |                        | ://smev3.gosuslugi.ru/portal/ |
        |    |                        | .                             |
        +----+------------------------+-------------------------------+

Результат:

Для работы с Программой сотрудник (программист) должен обладать компетенциями, перечисленными в таблице (см. tab_personal_example) в том объеме, который требуется для выполнения поставленных перед ним производственных задач.

Требования к персоналу (пример)
№	Компетенция	Уровень
1	Знакомство со СМЭВ 3	В объеме, изложенном в инструкциях, технологических стандартах, методических рекомендаций, регламентах и руководствах, приведенных на сайте https ://smev3.gosuslugi.ru/portal/ .

Блоки примечаний

Следует использовать два варианта примечаний:

.. attention:: - Внимание
.. note:: - Примечание

Пример:

.. attention:: Текст блока "Внимание!"

.. note:: - Текст блока "Примечание"

Результат:

Внимание

Текст блока «Внимание!»

Примечание

Текст блока «Примечание»

Вставка в текст исходного кода (листинг)

Исходный код можно добавить следующим образом:

При помощи команды из двух двоеточий ::

Приведем пример исходного кода::

        Пример исходного кода

При помощи команды .. code-block:: (рекомендуемый) т.к в этом случае можно указать язык программирования для исходного кода, например, json, sql, python и др.

Подключение файлов

(в разработке)

В документацию можно подключить уже готовый rst-файл с общим описанием, например, раздел «Назначение системы» или «Копирайт», которые располагаются в папке doc_reuse. Следует учитывать, что общие файлы следует изменять только после согласования со всеми разработчиками документации т.к. изменение общего файла, повлечет изменения всех документов, в которые он был ранее включен.

Файл в документацию подключается директивой .. include::. Путь к подключаемому файлу указывается через слэш (slash) следующего вида /. Не используйте обратный слэш \

.. include:: modules/doc_smev3_adapter/smev3_adapter.rst

Комментарии

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

.. Это комментарий

Многострочный комментарий

Важные особенности

Имена файлов в Sphinx

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

Примечание

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

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

Но вот пример ошибки: Sphinx собирает сайт, заходит в папку folder_1 видит там файл folder_1/chapter_1.rst с картинками и раздает им порядковые номера, например с 1 по 3. Далее идет в файл folder_1/chapter_2.rst и также раздает картинкам порядковые номера, например с 1 по 5. Все здорово пока. Но потом он переходит в папку folder_2 (это уже другой документ), видит там файл folder_2/chapter_1.rst с картинками. И раздает им нумерацию. Но не с 1, а сразу с номера 4!! А в файле folder_2/chapter_2.rst начнет уже с 6 номера))

Чтобы избежать данной ситуации, файлы в одном разделе надо называть folder_1/chapter_1_xxx.rst, а в другом folder_2/chapter_2_xxx.rst. В таком случае, мы сможем избежать некорректной нумерации вложенных картинок (и таблиц) в разных документах.