Стандартный синтаксис разметки reStructuredText

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

Что такое reStructuredText?

reStructuredText (сокращение: ReST, расширение файла: .rst) — облегчённый язык разметки, который может быть преобразован в различные форматы — HTML, ePub, PDF и другие.

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

Помимо этого, документы в формате .rst можно открывать и редактировать в любом простом текстовом редакторе (например, в Блокноте). Это позволяет работать над документацией в любых условиях, на любых платформах, без необходимости использовать специализированное программное обеспечение.

Самое главное, что ReST позволяет сосредоточиться исключительно на структуре документа и не отвлекаться на его оформление.

ReST аналогичен языку разметки Markdown, но обладает более расширенным синтаксисом, особенно вкупе с генератором документации Sphinx. ReST используется во многих проектах, например, на сайте GitHub. Также его используют многие генераторы статических сайтов такие, как: Hyde, Pelican и другие.

Редакторы reStructuredText

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

ReText

ReText (https://github.com/retext-project/retext) — редактор Markdown и reStructuredText для Linux. Есть возможность установки ReText в ОС Windows, инструкция находится здесь. Для Mac OS X репозиторий Homebrew: https://github.com/samueljohn/homebrew-python

Основные возможности редактора:

• Полная поддержка Markdown и reStructuredText, а также расширений Python-Markdown;

• Экспорт в HTML, PDF, ODT из коробки, а также возможность создавать свои собственные экспортные расширения (например, есть расширение для загрузки в Google Drive);

• Поддержка вкладок;

• Поддержка CSS-стилей и подсветка синтаксиса;

• Проверка орфографии (в том числе и для русского языка);

• Два движка просмотра: основанный на QTextBrowser и основанный на WebKit.

• Поддержка математических формул (с синтаксисом LaTeX).

Предупреждение

ReText не распознает конструкции, специфичные для Sphinx.

Примечание

Данное руководство написано с помощью ReText.

SublimeText

SublimeText (https://www.sublimetext.com/) — универсальный редактор большего количества форматов как для Linux так и для Windows. По умолчанию не поддерживает reStructuredText. Но есть специальные плагины:

Restructured​Text Improved (https://packagecontrol.io/packages/RestructuredText%20Improved) плагин добавляющий в SublimeText подсветку синтаксиса, а так же возможность перехода по заголовками используя комбинацию Control-R

Restructured Text (RST) Snippets (https://github.com/mgaitan/sublime-rst-completion) плагин добавляющий в SublimeText сниппеты основных конструкций, возможность геренерации Html/Pdf/Docx, и самое главное это возможность удобной работы с таблицами

GitGutter или Modific (https://github.com/jisaacks/GitGutter, https://github.com/gornostal/Modific) Данные плагины подсвечивают строки измененные последним коммитом, другими словами diff tools в режиме реального времени.

Online reStructuredText editor

Online reStructuredText editor (http://rst.ninjs.org) — простой онлайн-редактор reStructuredText.

NoTex.ch

NoTex.ch (https://www.notex.ch/) — онлайн-редактор с поддержкой reStructuredText, Markdown, LaTex и др. Поддерживает экспорт в PDF, HTML, EPUB, txt и LaTex.

rstext.me

rstext.me (http://rstext.me/) — онлайн-редактор reStructuredText с возможностью экспорта в разные форматы.

Синтаксис reStructuredText

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

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

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

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

1

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

Абзацы

Абзацы в ReST отделяются друг от друга пустой строкой:

Первый абзац...

Строки параграфов начинаются от левой границы
и отделяются параграфы друг от друга пустой строкой.

Заголовки

ReST поддерживает несколько уровней заголовков. Заголовки первого уровня (главы) подчеркиваются символом равно =. Заголовки второго уровня (подглавы) подчеркиваются символом короткого тире или минуса -. Заголовки третьего уровня (подпункта) подчеркиваются символом тильды ~. Для параграфов допускается использовать подчеркивание символами двойных кавычек "

Заголовки подчеркиваются (или отбиваются сверху и снизу) с помощью небуквенных и нецифровых 7­-битных ASCII символов. Рекомендуется использовать: «= ­ ` : ' " ~ ^ _ * + # < >». Отбивка должна быть не короче текста заголовка.

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

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

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

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

Начертание

Чтобы выделить текст жирным начертанием или курсивным используется обособление звездочками:

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

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

Внимание

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

Начертание текста «как есть» достигается обособлением двумя обратными кавычками:

``«как есть»``

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

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

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

Или:
5. Пять
6. Шесть
#. Семь

Результат:

1. Один

2. Два

3. Три

Или:

5. Пять

6. Шесть

7. Семь

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

Маркированные списки создаются с помощью символа звездочки * или дефиса -. Пробелы после маркера обязательны:

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

Результат:

• Один

• Два

• Три

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

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

Результат:

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

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

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

#. Один
    * Маркер
#. Два
    #. Номер

Результат:

1. Один

   • Маркер

2. Два

   1. Номер

Верхний и нижние индексы

Верхние и нижние индексы добавляются с помощью команд :sub: и :sup:.

H\ :sub:`2`\ O
E = mc\ :sup:`2`

Результат:

• H₂O

• E = mc²

Другой способ с помощью автозамены:

Химическая формула воды — |H2O|.

.. |H2O| replace:: H\ :sub:`2`\ O

Химическая формула воды — H₂O.

Определения

В ReST можно набрать два типа определений:

:Первый: В прямоугольном треугольнике квадрат длины
         гипотенузы равен сумме квадратов длин катетов.

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

Результат:

Первый

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

Второй

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

Цитаты

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

Основной текст:

    Цитата неизвестного человека

    --Аноним

Результат:

Цитата неизвестного человека

—Аноним

Эпиграф

.. epigraph::

   *«Если бы двери восприятия были чисты, всё
   предстало бы человеку таким, как оно есть — бесконечным»*

   -- Уильям Блэйк

Результат:

«Если бы двери восприятия были чисты, всё предстало бы человеку таким, как оно есть — бесконечным»

—  Уильям Блэйк

Оформление эпиграфа зависит от настроек HTML-темы или используемого шаблона LaTeX.

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

.. epigraph::

   *«Если бы двери восприятия были чисты, всё
   предстало бы человеку таким, как оно есть — бесконечным»*

   -- |nbsp| Уильям Блэйк

   .. |nbsp| unicode:: U+00A0

Сноски

Сноски могут быть разного вида:

Числовая сноска [5]_.

.. [5] Сюда ведет числовая сноска.

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

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

Авто­символ сносок используйте вот так [*]_ и [*]_.

.. [*] Это первый символ.
.. [*] Это второй символ.

Результаты:

Числовая сноска 5.

5

Сюда ведет числовая сноска.

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

2

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

3

Это вторая сноска.

Авто­символ сносок используйте вот так * и †.

*

Это первый символ.

†

Это второй символ.

Ссылки на цитаты выглядят так [CIT2002]_.

.. [CIT2002] Это цитата
(как часто используемая в журналах).

Ссылки на цитаты выглядят так [CIT2002].

CIT2002

Это цитата (как часто используемая в журналах).

При экспорте в PDF сноски автоматически располагаются в конце страницы. Чтобы цитата располагалась в конце HTML-страницы, необходимо команду сноски располагать в конце .rst файла [CIT2003].

Комментарии

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

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

Листинги (исходный код)

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

Посмотрим на исходный код:
::

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

Предупреждение

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

Существуют другие способы ввода команды ::, например:

Посмотрим на исходный код: ::

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

Или так:

Посмотрим на исходный код::

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

В данном случае команда :: будет верно истолкована, а двоеточие в тексте поставлено автоматически. Это более лаконичная форма записи.

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

Автозамены (Подстановки)

Язык reStructuredText — очень гибкий язык разметки, который поддерживает функцию автозамены (подстановки).

Язык |ReST| — очень гибкий язык разметки (подстановки).

.. |ReST| replace:: *reStructuredText*

Для удобства я в начале каждого файла делаю список автозамен.

Использование символов юникод (unicode)

С функцией автозамены связана функция вставки символов unicode:

Copyright |copy| 2015, |LibreRussia (TM)| |---| все права защищены.

.. |copy| unicode:: 0xA9 .. знак копирайта
.. |LibreRussia (TM)| unicode:: LibreRussia U+2122 .. символ торговой марки
.. |---| unicode:: U+02014 .. длинное тире

Получится такой результат:

Copyright © 2015, LibreRussia™ — все права защищены.

Дата и время

.. |date| date:: %d.%m.%Y
.. |time| date:: %H:%M

Текущая дата |date| и время |time|

Результат: Текущая дата 20.05.2022 и время 06:26 (на момент генерации документа).

Sphinx добавляет дополнительные команды автозамены, которые не требуют объявления. Подробнее о них написано в следующей главе.

Вставка текста из других файлов

ReST позволяет вставлять текст из других файлов:

.. include:: имя_файла

Черта (Линия)

Иногда возникает необходимость визуально отделить абзац, для этого можно воспользоваться чертой, достаточно поставить подряд несколько дефисов (не меньше 4-х), также можно воспользоваться нижним подчеркиванием:

--------

________

Предупреждение

Символы черты должны быть отбиты пустыми строками до и после.

Предупреждение

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

Ссылки

Внешние ссылки создаются так:

1. Внешние ссылки выглядят так: ссылка_.

.. _ссылка: http://librerussia.blogspot.ru/

2. Если несколько слов, тогда так: `ссылка в несколько слов`_.

.. _`ссылка в несколько слов`: http://librerussia.blogspot.ru/

3. `Более компактная запись ссылок <http://librerussia.blogspot.ru/>`_

Результат:

1. Внешние ссылки выглядят так: ссылка.

2. Если несколько слов, тогда так: ссылка в несколько слов.

3. Более компактная запись ссылок

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

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

.. _так:

Ссылками также являются и заголовки разделов, например, Таблицы :

Ссылка на раздел создается так `Таблицы`_ .
Достаточно в обратных кавычках написать название заголовка.

Sphinx расширяет возможности создания ссылок, в том числе позволяет ссылаться на заголовки в других документах. Подробнее читайте раздел Перекрестные ссылки.

Изображения и иллюстрации

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

Вставка изображения между слов |кубик-рубика| осуществляться с помощью функции автозамены:

.. |кубик-рубика| image:: _static/favicon.ico

Вставка изображений между абзацами осуществляется так:

.. figure:: _static/favicon.png
       :scale: 300 %
       :align: center
       :alt: Альтернативный текст

       Подпись изображения

       Легенда изображения.

Подпись изображения

Легенда изображения.

Параметр :scale: устанавливает масштаб изображений.

Параметр :align: устанавливает обтекание текстом, может принимать опции left, center или right.

Ещё один способ:

.. image:: picture.jpeg
   :height: 100px
   :width: 200 px
   :scale: 50 %
   :alt: alternate text
   :align: right

Таблицы

Создавать таблицы можно несколькими способами:

.. 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

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

.. table:: Простая таблица
    =====  =====  =======
      A      B    A and B
    =====  =====  =======
    False  False  False
    True   False  False
    False  True   False
    True   True   True
    =====  =====  =======

Результат:

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

A	B	A and B
False	False	False
True	False	False
False	True	False
True	True	True

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

.. 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-таблица:

.. 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-таблица

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!

Примечание

Смотрите также статью reStructuredText (ReST): Быстрый способ ввода таблиц

Ещё один тип таблицы — таблица в виде списка:

.. list-table:: Таблица в виде списка
   :widths: 15 10 30
   :header-rows: 1

   * - 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!

Таблица в виде списка

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!

Формулы

Вставка формул осуществляется командой .. math::. Для ввода формул используется синтаксис LaTeX:

.. math::

   \alpha_t(i) = P(O_1, O_2, … O_t, q_t = S_i \lambda)

Результат:

Sphinx расширяет возможности отображения формул, добавляя возможность ссылаться на них. Подробнее в разделе Вставка формул. Также смотрите раздел Некорректно отображаются формулы на Read The Docs.

Примечание

Таблица математических символов

Блоки примечаний и предупреждений

Блоки примечаний и предупреждений используются для сообщения дополнительной информации. Локализация заголовков и оформление блоков зависит от используемого шаблона. В стандартном шаблоне, используемом на сайте ReadTheDocs.org все блоки имеют собственное оформление, а локализация заголовков зависит от выбранного языка. Также язык настраивается в файле конфигурации Sphinx conf.py.

Внимание

Блок Внимание, команда: .. attention::

Осторожно

Блок Осторожно, команда: .. caution::

Опасно

Блок Опасно, команда: .. danger::

Ошибка

Блок Ошибка, команда: .. error::

Подсказка

Блок Подсказка, команда: .. hint::

Важно

Блок Важно, команда: .. important::

Примечание

Блок Примечание, команда: .. note::

Совет

Блок Совет, команда: .. tip::

Предупреждение

Блок Предупреждение, команда: .. warning::

Код блоков выглядит так:

.. tip:: Блок **Совет**, команда: ``.. tip::``

Содержание

На основе заголовков ReST автоматически создает оглавление, которое вставляется командой .. contents:::

.. contents:: Оглавление
   :depth: 2

или

.. contents:: Содержание
   :depth: 3

Параметр :depth: задает уровни заголовков, которые будут включены в оглавление.

Результат:

Оглавление

• Стандартный синтаксис разметки reStructuredText

  • Что такое reStructuredText?

  • Редакторы reStructuredText

  • Синтаксис reStructuredText

или

Содержание

• Стандартный синтаксис разметки reStructuredText

  • Что такое reStructuredText?

  • Редакторы reStructuredText

    • ReText

    • SublimeText

    • Online reStructuredText editor

    • NoTex.ch

    • rstext.me

  • Синтаксис reStructuredText

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

    • Абзацы

    • Заголовки

    • Начертание

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

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

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

    • Верхний и нижние индексы

    • Определения

    • Цитаты

    • Эпиграф

    • Сноски

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

    • Листинги (исходный код)

    • Автозамены (Подстановки)

    • Использование символов юникод (unicode)

    • Дата и время

    • Вставка текста из других файлов

    • Черта (Линия)

    • Ссылки

    • Изображения и иллюстрации

    • Таблицы

    • Формулы

    • Блоки примечаний и предупреждений

    • Содержание

    • Метаданные. Тег META

Метаданные. Тег META

Имеется возможность добавлять метаданные каждой из страниц непосредственно в rst файлы с помощью директивы .. meta:::

.. meta::
   :description: The reStructuredText plaintext markup language
   :keywords: plaintext, markup language

Будет преобразовано в:

<meta name="description"
content="The reStructuredText plaintext markup language">
<meta name="keywords" content="plaintext, markup language">

Другие атрибуты:

.. meta::
   :description lang=en: An amusing story
   :description lang=fr: Une histoire amusante

.. meta::
   :http-equiv=Content-Type: text/html; charset=ISO-8859-1

Подробнее смотрите раздел HTML-Specific официальной документации reStructuredText.

---

CIT2003

Код вставки этой цитаты .. [CIT2003] размещен в самом конце .rst файла.