rst.el

Встроенный пакет rst.el используется при работе с reStructured Text — основным форматом системы документирования Sphinx.

Настройки

rst-adjust-hook

Список команд, выполняемых после вызова rst-adjust.

Значение по умолчанию: nil.

rst-adornment-faces-alist

Список представлений шрифта, используемых для украшения (adornment) заголовков.

Значение по умолчанию:

'((t . rst-transition)
  (nil . rst-adornment)
  (1 . rst-level-1)
  (2 . rst-level-2)
  (3 . rst-level-3)
  (4 . rst-level-4)
  (5 . rst-level-5)
  (6 . rst-level-6))

rst-compile-toolsets

Список средств, используемых для преобразования открытого файла ReStructured Text в нужный формат.

Речь не о Sphinx и проектах, а об инструментах для сборки отдельных файлов.

Значение по умолчанию: зависит от целевого формата и найденных исполняемых файлов: если исполняемый файл не будет найден, использовать команду будет нельзя.

Формат Инструмент Расширение целевого файла

HTML

rst2html.py

.html

LaTeX

rst2latex.py

.tex

NewLaTeX

rst2newlatex.py

.tex

PseudoXML

rst2pseudoxml.py

.xml

XML

rst2xml.py

.xml

PDF

rst2pdf.py

.pdf

S5

rst2s5.py

.html

Имя целевого файла будет таким же, как у открытого, только с нужным расширением.

rst-default-indent

Если для оформления заголовков используются украшения, заголовки будут выравниваться с помощью указанного количества пробелов.

Значение по умолчанию: 1.

rst-indent-comment

Размер отступа для блоков с комментариями.

Значение по умолчанию: 3.

rst-indent-field

Размер отступа первой строки после поля. При значении 0 — выравнивание по содержимому.

Значение по умолчанию: 3.

rst-indent-literal-minimized

Размер отступа для литеральных блоков при использовании сокращённой разметки.

Значение по умолчанию: 2.

rst-indent-literal-normal

Размер отступа для литеральных блоков, использующих полную разметку.

Значение по умолчанию: 3.

rst-indent-width

Размер отступа.

Значение по умолчанию: 2.

rst-mode-hook

Список команд, выполняемых при включении rst-mode.

Эти команды выполняются после команд, привязанных к включению text-mode.

Значение по умолчанию: nil (пустой список).

rst-new-adornment-down

Уровень, используемый при украшении заголовка.

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

Возможные значения:

  • nil — такой же, как у предыдущего заголовка:

    =============
 Заголовок 1
=============

=============
 Заголовок 2
=============

=============
 Заголовок 3
=============

  • t — на уровень ниже чем у предыдущего заголовка:

    =============
 Заголовок 1
=============

Заголовок 2
===========

Заголовок 3
-----------

Значение по умолчанию: nil.

rst-preferred-adornments

Стили украшения заголовков.

Каждая запись состоит из трёх параметров:

  • Символ, используемый для украшения.

  • Стиль:

    • over-and-under — сверху и снизу;

    • simple — только снизу.

  • Отступ для текста.

Значение по умолчанию:

'((?= over-and-under 1)
  (?= simple 0)
  (?- simple 0)
  (?~ simple 0)
  (?+ simple 0)
  (?` simple 0)
  (?# simple 0)
  (?@ simple 0))

При таких значениях по умолчанию заголовки будут оформлены так:

===========
 Уровень 1
===========

Уровень 2
=========

Уровень 3
---------

Уровень 4
~~~~~~~~~

Уровень 5
+++++++++

Уровень 6
`````````

Уровень 7
#########

Уровень 8
@@@@@@@@@

rst-preferred-bullets

Список символов, используемых для оформления маркированных списков.

Значение по умолчанию: '(?* ?- ?+), т. е. маркерами считаются *, - и +.

rst-toc-indent

Отступ оглавления.

Значение по умолчанию: 2.

rst-toc-insert-max-level

Максимальный уровень заголовков, которые должны быть включены в оглавление.

Значение по умолчанию: nil (заголовки всех уровней).

rst-toc-insert-number-separator

Разделитель номера элемента оглавления и его заголовка.

Значение по умолчанию: ` ` (два пробела).

rst-toc-insert-style

Стиль оглавления.

Возможные значения:

  • plain — без нумерации, но с фиксированными отступами;

  • fixed — с нумерацией, но без фиксации отступов;

  • aligned — с нумерацией, заголовки выравниваются друг относительно друга;

  • listed — заголовки оформляются как элементы списка.

Значение по умолчанию: — fixed.

Рекомендации

Если вы работаете с reStructured Text в рамках Sphinx, имеет смысл переопределить некоторые настройки:

;; 📦 RST-MODE
;; Встроенный пакет для редактирования reStructutedText
;; https://www.writethedocs.org/guide/writing/reStructuredText/
(require 'rst)
(custom-set-variables
 '(rst-default-indent 3)
 '(rst-indent-comment 3)
 '(rst-indent-field 3)
 '(rst-indent-literal-minimized 3)
 '(rst-indent-width 3)
 '(rst-preferred-adornments '((?# over-and-under 1)
                              (?* over-and-under 1)
                              (?= simple 0)
                              (?- simple 0)
                              (?^ simple 0)
                              (?\" simple 0)))
 '(rst-toc-indent 3))