Стандартный синтаксис разметки 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 опирается на следующие концепции:
- Отступы и пробелы имеют значение для команд разметки [1], но не имеют значения внутри текста (10 пробелов будут отображены как один);
- В командах (директивах) используется символ обратной кавычки «`», который располагается на клавише с буквой
ё
и символом~
. Использование обычных одинарных кавычек в командах не приведет к желаемым результатам.
[1] | Не важно как делается отступ — пробелами или клавишей Tab, главное, чтобы они были одинакового размера. |
Абзацы¶
Абзацы в ReST отделяются друг от друга пустой строкой:
Первый абзац...
Строки параграфов начинаются от левой границы
и отделяются параграфы друг от друга пустой строкой.
Заголовки¶
ReST поддерживает несколько уровней заголовков. Заголовки первого уровня (главы) подчеркиваются символом равно =
. Заголовки второго уровня (подглавы) подчеркиваются символом короткого тире или минуса -
. Заголовки третьего уровня (подпункта) подчеркиваются символом тильды ~
. Для параграфов допускается использовать подчеркивание символами двойных кавычек "
Заголовки подчеркиваются (или отбиваются сверху и снизу) с помощью небуквенных
и нецифровых 7-битных ASCII символов. Рекомендуется использовать: «= ` : ' " ~ ^ _ * + # < >
». Отбивка должна быть не короче текста заголовка.
Заголовок 1 уровня
==================
Заголовок 2 уровня
------------------
Заголовок 3 уровня
~~~~~~~~~~~~~~~~~~
Заголовок 4 уровня
""""""""""""""""""
Начертание¶
Чтобы выделить текст жирным начертанием или курсивным используется обособление звездочками:
**жирный текст**
*курсив текст*
Attention
Не допускается наличие пробелов между выделяемым словом и звездочкой, например, команда ** жирный текст**
не даст нужного эффекта.
Начертание текста «как есть»
достигается обособлением двумя обратными кавычками:
``«как есть»``
Нумерованные списки¶
Нумерованные списки создаются с помощью символа решетки с точкой #.
:
#. Один
#. Два
#. Три
Или:
5. Пять
6. Шесть
#. Семь
Результат:
- Один
- Два
- Три
Или:
- Пять
- Шесть
- Семь
Маркированные списки¶
Маркированные списки создаются с помощью символа звездочки *
или дефиса -
. Пробелы после маркера обязательны:
* Один
* Два
* Три
Результат:
- Один
- Два
- Три
Вложенные списки¶
* Первый уровень
* Второй уровень
* Третий уровень
Результат:
- Первый уровень
- Второй уровень
- Третий уровень
#. Один
* Маркер
#. Два
#. Номер
Результат:
- Один
- Маркер
- Два
- Номер
Верхний и нижние индексы¶
Верхние и нижние индексы добавляются с помощью команд :sub:
и :sup:
.
H\ :sub:`2`\ O
E = mc\ :sup:`2`
Результат:
- H2O
- E = mc2
Другой способ с помощью автозамены:
Химическая формула воды — |H2O|.
.. |H2O| replace:: H\ :sub:`2`\ O
Химическая формула воды — H2O.
Определения¶
В 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. Комментарии создаются с помощью двух точек в начале предложения ..
. Для создания многострочных комментариев необходимо соблюдать отступ:
.. Это комментарий
Многострочный комментарий
Листинги (исходный код)¶
Если обособление обратными кавычками используется для визуального выделения команд в абзацах, то для примеров частей исходного кода используется команда из двух двоеточий ::
:
Посмотрим на исходный код:
::
Пример исходного кода
Warning
Пустая строка между командой ::
и примером кода, а также отступ перед ним, обязательны.
Существуют другие способы ввода команды ::
, например:
Посмотрим на исходный код: ::
Пример исходного кода
Или так:
Посмотрим на исходный код::
Пример исходного кода
В данном случае команда ::
будет верно истолкована, а двоеточие в тексте поставлено автоматически. Это более лаконичная форма записи.
Для вставки блоков исходного кода с подсветкой синтаксиса и нумерацией строк в 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|
Результат: Текущая дата 08.10.2017 и время 10:00 (на момент генерации документа).
Sphinx добавляет дополнительные команды автозамены, которые не требуют объявления. Подробнее о них написано в следующей главе.
Вставка текста из других файлов¶
ReST позволяет вставлять текст из других файлов:
.. include:: имя_файла
Черта (Линия)¶
Иногда возникает необходимость визуально отделить абзац, для этого можно воспользоваться чертой, достаточно поставить подряд несколько дефисов (не меньше 4-х), также можно воспользоваться нижним подчеркиванием:
--------
________
Warning
Символы черты должны быть отбиты пустыми строками до и после.
Warning
Черта не должна завершать документ. Черта, расположенная в самом конце документа может вызывать ошибки при сборке.
Ссылки¶
Внешние ссылки создаются так:
1. Внешние ссылки выглядят так: ссылка_.
.. _ссылка: http://librerussia.blogspot.ru/
2. Если несколько слов, тогда так: `ссылка в несколько слов`_.
.. _`ссылка в несколько слов`: http://librerussia.blogspot.ru/
3. `Более компактная запись ссылок <http://librerussia.blogspot.ru/>`_
Результат:
- Внешние ссылки выглядят так: ссылка.
- Если несколько слов, тогда так: ссылка в несколько слов.
Внутренние ссылки делаются так:
Внутренние ссылки делаются так_
.. _так:
Ссылками также являются и заголовки разделов, например, Таблицы :
Ссылка на раздел создается так `Таблицы`_ .
Достаточно в обратных кавычках написать название заголовка.
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. |
+------------------------+------------+---------------------+
Important
Отступ таблицы относительно команды .. 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. |
|
|
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!"
Результат:
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)
Результат:
Sphinx расширяет возможности отображения формул, добавляя возможность ссылаться на них. Подробнее в разделе Вставка формул. Также смотрите раздел Некорректно отображаются формулы на Read The Docs.
Блоки примечаний и предупреждений¶
Блоки примечаний и предупреждений используются для сообщения дополнительной информации. Локализация заголовков и оформление блоков зависит от используемого шаблона. В стандартном шаблоне, используемом на сайте 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:
задает уровни заголовков, которые будут включены в оглавление.
Результат:
Оглавление
или
Содержание
- Стандартный синтаксис разметки reStructuredText
- Что такое reStructuredText?
- Редакторы reStructuredText
- Синтаксис 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 файла. |