Расширение rst чем открыть

Обновлено: 15.01.2025

В главе приведен стандартный синтаксис разметки 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¶

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

Полная поддержка Markdown и reStructuredText, а также расширений Python-Markdown;
Экспорт в HTML, PDF, ODT из коробки, а также возможность создавать свои собственные экспортные расширения (например, есть расширение для загрузки в Google Drive);
Поддержка вкладок;
Поддержка CSS-стилей и подсветка синтаксиса;
Проверка орфографии (в том числе и для русского языка);
Два движка просмотра: основанный на QTextBrowser и основанный на WebKit.
Поддержка математических формул (с синтаксисом LaTeX).

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

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

SublimeText¶

Online reStructuredText editor¶

rstext.me¶

Синтаксис reStructuredText¶

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

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

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

Абзацы¶

Заголовки¶

. Для параграфов допускается использовать подчеркивание символами двойных кавычек "

Заголовки подчеркиваются (или отбиваются сверху и снизу) с помощью небуквенных и нецифровых 7-битных ASCII символов. Рекомендуется использовать: « = ` : ' "

Начертание¶

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

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

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

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

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

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

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

Первый уровень
- Второй уровень
  - Третий уровень
  Верхний и нижние индексы¶
  
  Верхние и нижние индексы добавляются с помощью команд :sub: и :sup: .
  
  Другой способ с помощью автозамены:
  
  Химическая формула воды — H₂O.
  
  Определения¶
  
  Первый: В прямоугольном треугольнике квадрат длины гипотенузы равен сумме квадратов длин катетов.
  
  Второй В прямоугольном треугольнике квадрат длины гипотенузы равен сумме квадратов длин катетов.
  
  Цитаты¶
  
  Для вставки цитат используется отступ, сделанный с помощью клавиши Tab :
  
  Цитата неизвестного человека
  
  —Аноним
  
  Эпиграф¶
  
  «Если бы двери восприятия были чисты, всё предстало бы человеку таким, как оно есть — бесконечным»
  
  — Уильям Блэйк
  
  Оформление эпиграфа зависит от настроек HTML-темы или используемого шаблона LaTeX.
  
  В американской типографике, в отличие от европейской, не принято отбивать тире пробелами. Чтобы получить пробел между тире и автором я использовал функцию Автозамены (Подстановки). В моем случае код эпиграфа выглядит так:
  
  Сноски¶
  
  Сноски могут быть разного вида:
  
  [5] Сюда ведет числовая сноска.
  
  Сноски с автоматической [2] нумерацией [3].
  
  [2] Это первая сноска.
  
  [3] Это вторая сноска.
  
  Автосимвол сносок используйте вот так [*] и [†].
  
  [*] Это первый символ.
  
  [†] Это второй символ.
  
  Ссылки на цитаты выглядят так [CIT2002].
  
  [CIT2002] Это цитата (как часто используемая в журналах).
  
  При экспорте в PDF сноски автоматически располагаются в конце страницы. Чтобы цитата располагалась в конце HTML-страницы, необходимо команду сноски располагать в конце .rst файла [CIT2003].
  
  Комментарии¶
  
  Листинги (исходный код)¶
  
  Если обособление обратными кавычками используется для визуального выделения команд в абзацах, то для примеров частей исходного кода используется команда из двух двоеточий :: :
  
  Пустая строка между командой :: и примером кода, а также отступ перед ним, обязательны.
  
  Существуют другие способы ввода команды :: , например:
  
  В данном случае команда :: будет верно истолкована, а двоеточие в тексте поставлено автоматически. Это более лаконичная форма записи.
  
  Для вставки блоков исходного кода с подсветкой синтаксиса и нумерацией строк в Sphinx используются специальные команды, подробнее смотрите раздел Примеры исходного кода с подсветкой синтаксиса .
  
  Автозамены (Подстановки)¶
  
  Язык reStructuredText — очень гибкий язык разметки, который поддерживает функцию автозамены (подстановки).
  
  Для удобства я в начале каждого файла делаю список автозамен.
  
  Использование символов юникод (unicode)¶
  
  С функцией автозамены связана функция вставки символов unicode:
  
  Получится такой результат:
  
  Copyright © 2015, LibreRussia™ — все права защищены.
  
  Дата и время¶
  
  Результат: Текущая дата 08.10.2017 и время 10:00 (на момент генерации документа).
  
  Sphinx добавляет дополнительные команды автозамены, которые не требуют объявления. Подробнее о них написано в следующей главе.
  
  Вставка текста из других файлов¶
  
  ReST позволяет вставлять текст из других файлов:
  
  Черта (Линия)¶
  
  Иногда возникает необходимость визуально отделить абзац, для этого можно воспользоваться чертой, достаточно поставить подряд несколько дефисов (не меньше 4-х), также можно воспользоваться нижним подчеркиванием:
  
  Символы черты должны быть отбиты пустыми строками до и после.
  
  Черта не должна завершать документ. Черта, расположенная в самом конце документа может вызывать ошибки при сборке.
  
  Ссылки¶
  
  Внешние ссылки создаются так:
  1. Внешние ссылки выглядят так: ссылка.
  1. Если несколько слов, тогда так: ссылка в несколько слов.
  Внутренние ссылки делаются так:
  
  Ссылками также являются и заголовки разделов, например, Таблицы :
  
  Sphinx расширяет возможности создания ссылок, в том числе позволяет ссылаться на заголовки в других документах. Подробнее читайте раздел Перекрестные ссылки .
  
  Изображения и иллюстрации¶
  
  Вставка изображения между слов осуществляться с помощью функции автозамены:
  
  Вставка изображений между абзацами осуществляется так:
  
  Параметр :scale: устанавливает масштаб изображений.
  
  Параметр :align: устанавливает обтекание текстом, может принимать опции left , center или right .
  
  Ещё один способ:
  
  Таблицы¶
  
  Создавать таблицы можно несколькими способами:
  
  Отступ таблицы относительно команды .. table:: обязателен
  
  Простая таблица ¶
  A B A and B
  
  False False False
  
  True False False
  
  False True False
  
  True True True
  
  Ещё один пример:
  
  Простая таблица со сложной шапкой ¶
  Inputs Output
  
  A B A or B
  
  False False False
  
  True False True
  
  False True True
  
  True True True
  
  Ещё один тип таблицы — CSV-таблица:
  
  Ещё один тип таблицы — таблица в виде списка:
  
  Формулы¶
  
  Вставка формул осуществляется командой .. math:: . Для ввода формул используется синтаксис LaTeX:
  
  $\alpha_t(i) = P(O_1, O_2, … O_t, q_t = S_i \lambda)$
  
  Sphinx расширяет возможности отображения формул, добавляя возможность ссылаться на них. Подробнее в разделе Вставка формул . Также смотрите раздел Некорректно отображаются формулы на Read The Docs .
  
  Блоки примечаний и предупреждений¶
  
  Блок Внимание, команда: .. attention::
  
  Блок Осторожно, команда: .. caution::
  
  Блок Опасно, команда: .. danger::
  
  Блок Ошибка, команда: .. error::
  
  Блок Подсказка, команда: .. hint::
  
  Блок Важно, команда: .. important::
  
  Блок Примечание, команда: .. note::
  
  Блок Совет, команда: .. tip::
  
  Блок Предупреждение, команда: .. warning::
  
  Код блоков выглядит так:
  
  Содержание¶
  
  На основе заголовков ReST автоматически создает оглавление, которое вставляется командой .. contents:: :
  
  Параметр :depth: задает уровни заголовков, которые будут включены в оглавление.
  
  Читайте также:

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

Inputs		Output
A	B	A or B
False	False	False
True	False	True
False	True	True
True	True	True

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

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

Цитаты¶

Эпиграф¶

Сноски¶

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

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

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

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

Дата и время¶

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

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

Ссылки¶

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

Таблицы¶

Формулы¶

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

Содержание¶