Шпаргалка RST

12 Июля 2013

Я использую ReStructuredText (он же ReST, он же RST) для написания документации, статей для блога и любого другого текста, который нужен в отформатированном виде. Основная причина моей симпатии - популярность в мире питонистов, интегрированность в замечательный Sphinx (который кстати используют далеко не только питонисты) и активное развитие в отличие от того же MD (который вообще откуда пришёл?). Но и этого всего было бы недостаточно, если бы не великолепный API для расширения возможностей ReST.

К сожалению, рост числа возможностей непременно ведёт к усложнению работы, и многие полезные фичи скрыты под кучей страниц малопонятной документации. Тут как можно более кратко я опишу (попробую, по крайней мере) самые полезные на мой взгляд возможности. Я не ручаюсь за правильность всего написанного, но сам пользуюсь этой шпаргалкой и мне нравится.

Кто есть кто

docutils: написанная на Python библиотека-процессор для документов написанных с помощью разметки ReST, и основная зависимость приложений работающих с этими документами. Предоставляет вышеупомянутый API для раширения возможностей ReST (роли и директивы), а так же несколько скриптов для конвертации в другие форматы.
Sphinx: генератор документации. Естественно, активно использует docutils, расширяя возможности (ссылки, тестирование сниппетов, вставка контента и куча всего) и стили. Нечто отдалённо напоминающее Pelican, но с упором на документацию, хотя многие используют как генератор статичного сайта со статьями и заметками.
Директивы: основной способ расширения ReST. Определяют в основном элементы, которые пользователь будет видеть (изображения, видео, LaTeX, предупреждения). Многие директивы включены в docutils, но пользовательское приложение может добавлять свои директивы, явно определяя на питоне, какие могут приниматься аргументы, должен ли быть контент и как они должны конвертироваться в каждый формат.
Роли: примерно то же самое что и директивы, но умещаются в одну строку и не подразумевают аргументов, только контент (хотя можно конечно и реализовать чисто теоретически). Примеры: восклицание, строчный LaTeX, заголовок и т.д.
Doctree: то как наш документ выглядит для машины. Построив doctree, docutils будут обрабатывать эту структуру данных и преобразовывать в необходимый формат. Для простого автора явно ненужное понятие.
Field Lists: метаинформация о документе, представленная в виде :ключ: значение. Описывает произвольные данные (метки, автор, дата публикации, статус), которые могут быть использованы директивами или другими обработчиками и скорее всего не будут отображены явно. В блоге я задаю с помощью них URL, описание, приоритет в sitemap.xml и прочую служебную информацию.

Шпаргалка

Важно отметить, что у значительной части этого функционала сущетсвует несколько возможных реализаций, другие могут быть специфичны для Sphinx, Pelican или конкретной версии docutils. Например, список может быть оформлен с помощью любого из этих символов: "*", "+", "-", "•", "‣", или "⁃", но я пользуюсь только "+". Поэтому я опишу лишь те, которыми пользуюсь сам.

Списки

+ Элемент раз

  - Вложенный элемент
  - Вложенный элемент растянувшийся
    на несколько строк

+ Элемент два

Ссылки

`Текст ссылки <http://example.com>`_

Текст

*акцентированный текст (курсив)*
**выделенный текст (жирное начртание)**
:code:`print("hello world")   # код, как можно догадаться. Пример роли

Дополнительно

Особый интерес представляет интерпретируемый текст (заключается в обратные кавычки `как этот`). Этот текст может быть представлен как любой элемент doctree в зависимости от роли, которой он передан (пример с кодом выше). Так же есть возможнось определить роль по умолчанию для документа.

Код

Классы директив должны наследоваться от docutils.parsers.rst.Directive. Дочерние классы могут устанавливать следующие атрибуты: required_arguments, optional_arguments, final_argument_whitespace, has_content. Подробнее о них можно узнать в __doc__.

Регистрация директивы

В случае если вы создаёте директиву общего назначения, она может быть добавлена в словарь _directive_registry в docutils/parsers/rst/directives/__init__.py.

Если это директива написана специально для вашего приложения, используйте функцию register_directive:

from docutils.parsers.rst import directivesdirectives
register_directive(directive_name, directive_class)

Все стандартные директивы реализованы в docutils/parsers/rst/directives