Стандартный синтаксис разметки 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).

Warning

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

Note

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

SublimeText

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

RestructuredText 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 опирается на следующие концепции:

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

Абзацы

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

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

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

Заголовки

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

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

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

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

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

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

Начертание

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

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

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

Attention

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

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

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

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

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

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

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

Результат:

Один
Два
Три

Или:

Пять
Шесть
Семь

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

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

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

Результат:

Один
Два
Три

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

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

Результат:

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

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

Результат:

Один
- Маркер
Два
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 (reStructuredText) можно набрать два типа определений: :

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

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

Результат:

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

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

Цитаты

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

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

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

    --Аноним

Результат:

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

--Аноним

Эпиграф

.. epigraph::

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

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

Результат:

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

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

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

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

.. epigraph::

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

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

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

Сноски

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

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

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

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

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

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

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

Результаты:

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

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

Автосимвол сносок используйте вот так⁵ и⁶.

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

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

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

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

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

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

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

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

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

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

Warning

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

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

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

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

Или так:

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

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

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

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

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

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

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

.. |ReST| replace:: *reStructuredText*

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

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

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

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

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

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

Дата и время

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

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

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

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

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

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

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

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

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

--------

________

Warning

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

Warning

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

Ссылки

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

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

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

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

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

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

Результат:

Внешние ссылки выглядят так: ссылка.
Если несколько слов, тогда так: ссылка в несколько слов.
Более компактная запись ссылок

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

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

.. _так:

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

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

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

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

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

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

.. |кубик-рубика| 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.    |
    +------------------------+------------+---------------------+

Important

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

Результат:

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

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

Note

Смотрите также статью 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)

Результат:

α_t(i) = P(O₁, O₂, …O_t, q_t = S_iλ)

Sphinx расширяет возможности отображения формул, добавляя возможность ссылаться на них. Подробнее в разделе math-insert-label. Также смотрите раздел math-errors2-label.

Note

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

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

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

Attention

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

Caution

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

Danger

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

Error

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

Hint

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

Important

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

Note

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

Tip

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

Warning

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

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

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

Содержание

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

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

или

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

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

Результат:

Оглавление

или

Содержание

Метаданные. Тег 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.

CIT2002: Это цитата (как часто используемая в журналах).
CIT2003: Код вставки этой цитаты .. [CIT2003] размещен в самом конце .rst файла.

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

rst-markup.rst

rst-markup.rst

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

Что такое reStructuredText?

Редакторы reStructuredText

ReText

SublimeText

Online reStructuredText editor

NoTex.ch

rstext.me

Синтаксис reStructuredText

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

Абзацы

Заголовки

Начертание

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

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

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

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

Определения

Цитаты

Эпиграф

Сноски

Комментарии

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

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

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

Дата и время

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

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

Ссылки

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

Таблицы

Формулы

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

Содержание

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

Files

rst-markup.rst

Latest commit

History

rst-markup.rst

File metadata and controls

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

Что такое reStructuredText?

Редакторы reStructuredText

ReText

SublimeText

Online reStructuredText editor

NoTex.ch

rstext.me

Синтаксис reStructuredText

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

Абзацы

Заголовки

Начертание

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

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

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

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

Определения

Цитаты

Эпиграф

Сноски

Комментарии

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

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

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

Дата и время

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

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

Ссылки

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

Таблицы

Формулы

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

Содержание

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