=============================================== Синтаксис разметки reStructuredText =============================================== Базовые концепции ----------------- Синтаксис reStructuredText опирается на следующие концепции: Отступы и пробелы имеют значение для команд разметки, но не имеют значения внутри текста (10 пробелов будут отображены как один). .. note:: Не важно как делается отступ — пробелами или клавишей Tab, главное, чтобы они были одинакового размера. В командах (директивах) используется символ обратной кавычки `````, который располагается на клавише с буквой ``ё`` и символом ``~`` Заголовки --------- .. note:: Длина подчеркивания должна быть равна длине заголовка! .. code-block:: rst Заголовок 1 уровня ================== Заголовок 2 уровня ------------------ Заголовок 3 уровня ~~~~~~~~~~~~~~~~~~ Заголовок 4 уровня ^^^^^^^^^^^^^^^^^^ Заголовок 5 уровня ################## .. attention:: Рекомендуется не использовать заголовки ниже 4 уровня. Выделение текста ---------------- .. code-block:: rest **жирный текст** *курсив текст* Выделение текста красным цветом, например, вот так: ``красный цвет``, выполняется двумя обратными кавычками .. code-block:: rest ``красный цвет`` Такое выделение следует использовать при написании имени модуля, файла, папки, параметра, запроса, порта и т.д. Нумерованные списки ------------------- Для нумерованных списков следует использовать символ ``#.`` .. code-block:: rest #. Один #. Два #. Три или 1. Один 2. Два 3. Три Результат: #. Один #. Два #. Три Сложные нумерованные списки: Для того чтобы нумерованный список продолжился нужно поставить пробел(см. пример)! .. code-block:: rest #. Текст первого пункта #. Текст второго пункта #. Этот пункт нам надо разбить еще на два пункта: #. подпункт номер один #. подпункт номер два #. Текст четвертого пункта - это маркированный список четвертого пункта - здесь сделаем второй пункт #. Продолжим нумерованный список Продолжаем наш текст Результат: #. Текст первого пункта #. Текст второго пункта #. Этот пункт нам надо разбить еще на два пункта: #. подпункт номер один #. подпункт номер два #. Текст четвертого пункта - это маркированный список четвертого пункта - здесь сделаем второй пункт А здесь продолжим наш текст новым абзацем... Маркированные списки -------------------- Для маркированных списков следует использовать символ ``*`` или ``*``. .. code-block:: rest * Один * Два * Три Результат: * Один * Два * Три Вложенные списки ---------------- .. code-block:: rest * Первый уровень * Второй уровень * Третий уровень Результат: * Первый уровень * Второй уровень * Третий уровень Изображения ----------- Вставка изображения ~~~~~~~~~~~~~~~~~~~ Для вставки изображения используйте следующий код: .. code-block:: rest .. _fig1: .. figure:: img/insert_image.png :align: center :alt: Вставка изображения (альтернативный текст для html) Вставка изображения (подрисуночная подпись) Результат: .. _fig1: .. figure:: img/insert_image.png :align: center :alt: Вставка изображения Вставка изображения Вставка изображения в тексте ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Вставка изображения между слов, например, вот такого значка |обновление| осуществляться с помощью функции автозамены. .. |обновление| image:: img/image_in_text.png Пример кода:: 1. Вставка изображения между слов, например, вот такого значка |обновление| осуществляться с помощью функции автозамены. .. |обновление| image:: img/image_in_text.png Вставка ссылки на изображение ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Для вставки ссылки на изображение используйте ссылку на ``якорь`` вида ``:numref:`fig1```. Например, чтобы сослаться на изображение выше, сделайте следующие: .. code-block:: rest Это просто текст, но сейчас мы в нем сделаем ссылку на :numref:`fig1`: Результат: Это просто текст, но сейчас мы в нем сделаем ссылку на :numref:`fig1`: .. _link: Ссылки и сноски --------------- Внешние ссылки ~~~~~~~~~~~~~~ Пример кода для вставки внешней ссылки: .. code-block:: rest Вот здесь расположена `ссылка на сайт IT-ONE `_ Результат: Вот здесь расположена `ссылка на сайт IT-ONE `_ Перекресные ссылки ~~~~~~~~~~~~~~~~~~ Есть два способа вставки перекресных ссылок. **Способ 1 (простой)** В тексте можно просто указать название раздела, на который вы планируете поставить ссылку, например: .. code-block:: rest Здесь мы сделаем ссылку на раздел `Ссылки и сноски`_ Просто укажите название раздела в обратных кавычках, при этом учтите, раздел должен существовать в структуре документации. Результат: Здесь мы сделаем ссылку на раздел `Ссылки и сноски`_ .. attention:: При изменении названия раздела ссылка станет неактивной. **Способ 2 (с использованием ``якоря``)** При использовании ``якоря``, название текста ссылки будет автоматически добавляться из названия заголовка перед которым установлен ``якорь``. При изменении заголовка, текст ссылки также изменит название. Для использования этого способа необходимо выполнить следующие: #. Установить ``якорь`` вида: ``.._name_chapter:`` перед разделом, на который будет вести ссылка. Между ``якорем`` и заголовком должна быть пустая строка (см. рис. ниже). .. figure:: img/link.png :align: center :alt: Вставка якоря перед заголовком Вставка якоря перед заголовком #. Установить в нужное место текста ссылку ввида ``:ref:`name_chapter``` Пример кода: .. code-block:: rest Здесь мы сделаем ссылку на раздел выше :ref:`link` Результат: Здесь мы сделаем ссылку на раздел выше :ref:`link` **Способ 3 (внутренние ссылки)** В этом способе .. code-block:: rest Внутренние ссылки делаются так: ссылка_на_примечание_ Далее, в тексте вставляем в нужное место ``.. _ссылка_на_примечание:``, в нашем примере мы установили ссылку над блоком "Примечание", в разделе "Таблицы". Проверим результат: .. ссылка на примечание в разделе Таблицы Внутренние ссылки делаются так: ссылка_на_примечание_ Ссылки на файлы (текстовые и для загрузки) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Допустим, есть структура документации:: > a >> a_foo >>> a_bar > b >> b_foo > c Для ссылки из любого места:: :doc:`link to a :doc:`link to a_foo ` из a :doc:`relative link to a_foo <./a/foo>` Cноски ~~~~~~ Рекомендуется использовать сноски с автоматической нумерацией. При этом сноски старайтесь располагать рядом с текстом, в котором они используются. .. code-block:: rest Сноски с автоматической [#]_ нумерацией [#]_. .. [#] Это первая сноска. .. [#] Это вторая сноска. Результат: Сноски с автоматической [#]_ нумерацией [#]_. .. [#] Это первая сноска. .. [#] Это вторая сноска. Таблицы ------- Работа с таблицами ~~~~~~~~~~~~~~~~~~ Есть несколько способов сделать таблицы. .. code-block:: rest .. 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. | +------------------------+------------+---------------------+ .. _ссылка_на_примечание: .. note:: Отступ таблицы относительно команды .. table:: обязателен Результат: .. _tab_example: .. 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. | +------------------------+------------+---------------------+ Простая таблица .. code-block:: rest .. table:: Простая таблица со сложной шапкой ===== ===== ====== Inputs Output ------------ ------ A B A or B ===== ===== ====== False False False True False True False True True True True True ===== ===== ====== Результат: .. table:: Простая таблица со сложной шапкой ===== ===== ====== Inputs Output ------------ ------ A B A or B ===== ===== ====== False False False True False True False True True True True True ===== ===== ====== .. code-block:: rest .. csv-table:: CSV-таблица :header: "Treat", "Quantity", "Description" :widths: 15, 10, 30 "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-table:: CSV-таблица :header: "Treat", "Quantity", "Description" :widths: 15, 10, 30 "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!" Вставка ссылки на таблицу ~~~~~~~~~~~~~~~~~~~~~~~~~ Для вставки в текст документации ссылки на таблицу, как и при работе с изображениями, используйте ссылку на ``якорь``. #. Установите перед таблицей ``якорь`` (см. рис. ниже). .. figure:: img/link_table.png :align: center :alt: Вставка якоря перед заголовком Вставка якоря перед заголовком таблицы #. В тексте установите ссылку на якорь вида вида ``:numref:`tab_example``` .. attention:: После названия таблицы должна быть пустая строка и таблица должна иметь отступ от левого края (клавиша **TAB** для всей таблицы). Например, чтобы сослаться на таблицу выше, используйте следующий код: .. code-block:: rest Посмотрите как можно перейти вот на эту таблицу (см. :numref:`tab_example`) Результат: Посмотрите как можно перейти вот на эту таблицу (см. :numref:`tab_example`) .. note:: - В названии ``якоря`` используйте префикс ``tab`` Еще один пример: .. code-block:: rest Для работы с Программой сотрудник (программист) должен обладать компетенциями, перечисленными в таблице (см. :numref:`tab_personal_example`) в том объеме, который требуется для выполнения поставленных перед ним производственных задач. .. _tab_personal_example: .. table:: Требования к персоналу (пример) +----+------------------------+-------------------------------+ | № | Компетенция | Уровень | +====+========================+===============================+ | 1 | Знакомство со СМЭВ 3 | В объеме, изложенном в | | | | инструкциях, технологических | | | | стандартах, методических | | | | рекомендаций, регламентах и | | | | руководствах, приведенных на | | | | сайте | | | | https | | | | ://smev3.gosuslugi.ru/portal/ | | | | . | +----+------------------------+-------------------------------+ Результат: Для работы с Программой сотрудник (программист) должен обладать компетенциями, перечисленными в таблице (см. :numref:`tab_personal_example`) в том объеме, который требуется для выполнения поставленных перед ним производственных задач. .. _tab_personal_example: .. table:: Требования к персоналу (пример) +----+------------------------+-------------------------------+ | № | Компетенция | Уровень | +====+========================+===============================+ | 1 | Знакомство со СМЭВ 3 | В объеме, изложенном в | | | | инструкциях, технологических | | | | стандартах, методических | | | | рекомендаций, регламентах и | | | | руководствах, приведенных на | | | | сайте | | | | https | | | | ://smev3.gosuslugi.ru/portal/ | | | | . | +----+------------------------+-------------------------------+ Блоки примечаний ---------------- Следует использовать два варианта примечаний: - ``.. attention::`` - Внимание - ``.. note::`` - Примечание Пример: .. code-block:: rest .. attention:: Текст блока "Внимание!" .. note:: - Текст блока "Примечание" Результат: .. attention:: Текст блока "Внимание!" .. note:: - Текст блока "Примечание" Вставка в текст исходного кода (листинг) ---------------------------------------- Исходный код можно добавить следующим образом: 1. При помощи команды из двух двоеточий ``::`` .. code-block:: rest Приведем пример исходного кода:: Пример исходного кода 2. При помощи команды ``.. code-block::`` (рекомендуемый) т.к в этом случае можно указать язык программирования для исходного кода, например, ``json``, ``sql``, ``python`` и др. .. _fig_listing: .. figure:: img/listing.png :align: center :alt: Вставка исходного кода Вставка исходного кода Подключение файлов ------------------ (в разработке) В документацию можно подключить уже готовый rst-файл с общим описанием, например, раздел "Назначение системы" или "Копирайт", которые располагаются в папке ``doc_reuse``. Следует учитывать, что общие файлы следует изменять только после согласования со всеми разработчиками документации т.к. изменение общего файла, повлечет изменения всех документов, в которые он был ранее включен. Файл в документацию подключается директивой ``.. include::``. Путь к подключаемому файлу указывается через слэш (slash) следующего вида ``/``. Не используйте обратный слэш ``\`` .. code-block:: rest .. include:: modules/doc_smev3_adapter/smev3_adapter.rst Комментарии ----------- В ReST можно оставлять комментарии, которые отображаются только в исходном файле ReST. Комментарии создаются с помощью двух точек в начале предложения ``..``. Для создания многострочных комментариев необходимо соблюдать отступ:: .. Это комментарий Многострочный комментарий Важные особенности ------------------ Имена файлов в Sphinx ~~~~~~~~~~~~~~~~~~~~~ В процессе эксплуотации текущей версии выяснилась особенность, влияющая на нумерацию картинок, вложенных в файлы. .. note:: Важно, чтобы имена файлов в разных разделах документации не повторялись В противном случае, обнаруживается проблема с нумерацией. В конфиге настроено так что для каждого раздела все картинки должны нумероваться с 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*. В таком случае, мы сможем избежать некорректной нумерации вложенных картинок (и таблиц) в разных документах.