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

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

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

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

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

Абзацы¶

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

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

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

Заголовки¶

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

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

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

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

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

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

Начертание¶

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

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

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

Внимание

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

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

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

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

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

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

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

Результат:

Один
Два
Три

Или:

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

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

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

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

Результат:

Один
Два
Три

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

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

Результат:

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

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

Результат:

Один
- Маркер
Два
1. Номер

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

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

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

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

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

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

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

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

--------

________

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

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

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

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

Ссылки¶

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

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

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

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

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

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

Результат:

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

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

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

Таблицы¶

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

.. 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:: Простая таблица
    =====  =====  =======
      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!

Конструкции разметки Sphinx¶

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

Автоматическое содержание¶

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

Файл index.rst обычно содержит автоматическое оглавление, созданное командой .. toctree:::

.. toctree::
   :maxdepth: 2
   :numbered:
   :hidden:

   имя_документа1
   имя_документа1
   имя_документа1

Команда .. toctree:: имеет несколько параметров:

:maxdepth: — уровни заголовков, включаемых в оглавление;
:numbered: — нумерация всех пунктов оглавления;
:hidden: — позволяет скрыть оглавление.

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

Параметр :maxdepth: не распространяется на LaTeX-документы. Глубина оглавления в LaTeX контролируется его внутренним счетчиком, который можно настроить в файле конфигурации Sphinx conf.py, указав в преамбуле значение \setcounter{tocdepth}{2}.

Параметр :hidden: позволяет Sphinx’у быть в курсе структуры документа, но при этом не отображать оглавление. Удобно, если ссылки на разделы будут указаны, например, на боковой панели.

Подробнее об автоматическом оглавлении в Sphinx смотрите в разделе «The TOC tree» официальной документации Sphinx.

Примеры исходного кода с подсветкой синтаксиса¶

Sphinx поддерживает вставку примеров исходного когда с подсветкой синтаксиса на разных языках программирования. Вставка листингов осуществляется командой .. code-block:: <название яыка>:

.. code-block:: python

   def some_function():
       interesting = False
       print 'This line is highlighted.'
       print 'This one is not...'
       print '...but this one is.'

Результат:

def some_function():
    interesting = False
    print 'This line is highlighted.'
    print 'This one is not...'
    print '...but this one is.'

Команда .. code-block:: имеет следующие параметры:

:linenos: — добавляет нумерацию строк;
:emphasize-lines: — включает подсветку отдельных строк, допускается перечисление одиночных строк через запятую или групп строк через тире.

Больше элементов синтаксиса reStructuredText и Sphinx можно найти здесь.