Sphinx и ReStructured Text

Допустим, проект на Sphinx создан, правки в conf.py сделаны.

Что дальше?

Самое время настроить редактор на работу с ReStructured Text, также известным как ReST (не путайте с REST — это 2 разных технологии).

Хорошая новость — пакет rst-mode в Emacs «из коробки».
Плохая новость — он не очень умный.

Давайте сделаем кое-какие настройки:

;; -> RST-MODE
;; Основной режим для редактирования reStructutedText
;; Встроенный пакет.
;; Больше здесь: https://www.writethedocs.org/guide/writing/reStructuredText/
(use-package rst
  :ensure t
  :defer t
  :custom
  (rst-default-indent 3)
  (rst-indent-comment 3)
  (rst-indent-field 3)
  (rst-indent-literal-minimized 3)
  (rst-indent-width 3)
  (rst-toc-indent 3)
  :mode
  (("\\.rest\\'" . rst-mode)
   ("\\.rst\\'" . rst-mode)
   ("\\.txt\\'" . rst-mode)))

Отступы теперь строго регламентированы — 3 пробела. При открытии файлов с расширениями .rest, .rst и .txt теперь автоматически включается rst-mode.

При включении rst-mode необходимо включить множество минорных режимов. В моей конфигурации используются эти:

• display-line-numbers-mode
• flycheck-mode
• flymake-mode
• flyspell-mode
• rainbow-delimiters-mode
• whitespace-mode
• ws-butler-mode

Я специально не включаю company-mode, т. к. лично мне он больше мешает, чем помогает.

Как включить эти режимы?

Императивный стиль:

(add-hook 'rst-mode-hook #'display-line-numbers-mode)
(add-hook 'rst-mode-hook #'flycheck-mode)
(add-hook 'rst-mode-hook #'flymake-mode)
(add-hook 'rst-mode-hook #'flyspell-mode)
...

При использовании use-package добавьте в блок :hook для нужных пакетов название режима rst-mode, например:

(use-package ws-butler
  :pin "NONGNU"
  :ensure t
  :defer t
  :hook
  ((
    adoc-mode
    conf-mode
    markdown-mode
    rst-mode
  ) . ws-butler-mode))

#sphinx #rst

Sphinx и Flycheck

Было бы здорово узнавать об ошибках в вёрстке до того, как документация попадёт на прод. Что может предложить Flycheck? А он в версии из репозитория stable.melpa.org, может предложить следующие средства:

• rst-sphinx
• rst
• textlint

Чтобы работали первые 2, достаточно активировать созданное для проекта виртуальное окружение. Если Sphinx в него установлен, Flycheck активирует эти средства повышения качества кода автоматически.

С textlint сложнее.
1. Ему для работы нужен NodeJS.
2. Требуется конфигурационный файл с настройками.
3. textlint (насколько мне известно) работает только с англоязычными текстами.

Из-за пунктов 2 и 3 я не использую его в работе, и в этой статье его настройка не рассматривается.

Что ж, перейдём к настройке.

1. В терминале активируйте виртуальное окружение проекта:

source .venv/bin/activate

2. Установите sphinx, если он не установлен:

pip install sphinx

3. Запустите Emacs.
4. Добавьте в init.el настройки для Flycheck:

;; -> FLYCHECK
;; https://flycheck.org
;; Проверка синтаксиса на лету с помощью статических анализаторов
(use-package flycheck
  :pin "MELPA-STABLE"
  :ensure t
  :defer t
  :custom
  (flycheck-check-syntax-automatically '(mode-enabled save new-line))
  (flycheck-highlighting-mode 'lines "Стиль отображения проблемных мест — вся строка")
  (flycheck-indication-mode 'left-fringe "Место размещения маркера ошибки — левая граница")
  (flycheck-locate-config-file-functions '(
                                           flycheck-locate-config-file-by-path
                                           flycheck-locate-config-file-ancestor-directories
                                           flycheck-locate-config-file-home))
  :hook
  ((
    emacs-lisp-mode
    markdown-mode
    python-mode
    rst-mode
    ) . flycheck-mode))

5. Выполните содержимое буфера с init.el:

eval-buffer

6. Активируйте виртуальное окружение с помощью pyvenv-activate.
7. Откройте любой файл проекта ([Ctrl-x, Ctrl-f], find-file).
8. Проверьте статус Flycheck: [Ctrl-c, !, v].

Вывод должен быть примерно таким:

Syntax checkers for buffer task.rst in rst-mode:

First checker to run:

  rst-sphinx
    - may enable: yes
    - predicate:  t
    - executable: Found at /home/***/repo/*******/.venv/bin/sphinx-build

Checkers that could run if selected:

  rst  select
    - may enable: yes
    - executable: Found at /home/***/repo/******/.venv/bin/rst2pseudoxml.py

Checkers that are compatible with this mode, but will not run until properly configured:

  textlint (disabled)
    - may enable:         Automatically disabled!
    - executable:         Not found
    - configuration file: Not found
    - textlint plugin:    @textlint/text

Flycheck Mode is enabled.  Use C-u C-c ! x to enable disabled
checkers.

--------------------

Flycheck version: 32
Emacs version:    28.2
System:           x86_64-pc-linux-gnu
Window system:    x

Обратите внимание, что используется версия Sphinx, установленная в активном виртуальном окружении.

#sphinx #flycheck

Давайте расскажу, как я запускаю компиляцию Sphinx.

1. Вызываю projectile-compile-project с помощью [C-x p c]. Там у меня уже прописана команда make dirhtml. Как это сделать я писал раньше.
2. Жму [RET]. Открывается отдельное окно, в которое пишется вывод команды компиляции, в моём случае это make dirhtml.
3. Перехожу в это окно с помощью [C-x o] и спускаюсь в самый низ с помощью [M->] ([Alt+Shift+.]), чтобы видеть самые свежие строки.
4. Если вывод без ошибок — закрываю окно с помощью [C-x 5 0].
5. Если есть ошибки, то можно перейти к проблемному месту с помощью ссылки. Если ссылки нет, можно перейти к предполагаемому месту, открыв нужный файл с помощью projectile-find-file [C-x p f].
6. Делаю правки.
7. Можно повторно вызвать projectile-compile-command, а можно вернуться в буфер *compilation* и просто попросить Emacs обновить содержимое: нажать клавишу [g].

#projectile #sphinx