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

Обновлено: 07.07.2024

В главе приведен стандартный синтаксис разметки 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: задает уровни заголовков, которые будут включены в оглавление.
  
  Читайте также:

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

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

Что такое reStructuredText?¶

Редакторы reStructuredText¶

ReText¶

SublimeText¶

Online reStructuredText editor¶

rstext.me¶

Синтаксис reStructuredText¶

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

Абзацы¶

Заголовки¶

Начертание¶

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

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

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

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

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

Цитаты¶

Эпиграф¶

Сноски¶

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

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

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

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

Дата и время¶

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

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

Ссылки¶

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

Таблицы¶

Формулы¶

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

Содержание¶