Кастомизация сборки PDF через LaTeX

Эти рекомендации предназначены для проектов, использующих сборку PDF через LaTeX. Для новых проектов рекомендуется использовать сборку PDF через WeasyPrint.

На внешний вид документации, собираемой через LaTeX, могут влиять сразу несколько разных настроек и файлов. Часть из них определяется напрямую в конфиге вашего проекта, а часть загружается из директории темы оформления, указанной в настройке latex.theme. Все настройки и файлы опциональны.

Шпаргалка. Код LaTeX формируется в следующем порядке:

  1. объявления путей,
  2. объявления переменных,
  3. стили (из темы),
  4. дополнительные объявления для документа,
  5. открытие блока с содержимым,
  6. обложка (из темы),
  7. оглавление (из темы),
  8. обработанное плагином содержимое всех страниц,
  9. закрытие блока с содержимым.

Пути #

Некоторые конструкции в LaTeX требуют абсолютных путей к дополнительным файлам. Например, если для оформления обложки вы используете команду LaTeX \includesvg, вам могут потребоваться абсолютные пути к логотипам и другим элементам фирменного стиля.

С помощью настройки latex.paths вы можете перечислить пути к необходимым вам директориям в проекте. Собирака передаст пути в LaTeX в виде команд, предварительно преобразовав каждый путь в абсолютный.

Пример. Допустим, что проект находится в директории /home/user/mydocs. Следующая конфигурация определит команду \IMAGES, возвращающую путь /home/user/mydocs/resources/images/. Её можно будет использовать в LaTeX как любую другую команду, например: \includesvg{\IMAGES/logo.svg}.

pdf-latex:
  paths:
    IMAGES: resources/images

Переменные #

Собирака объявляет в LaTeX следующие команды-переменные:

  • \TITLE — заголовок документа (см. настройку title);
  • \LANG — идентификатор языка документа (см. Мультиязычность);
  • все переменные, заданные с помощью настройки variables.

Пример. Следующая конфигурация определит команды \PRODUCT и \VERSION. Их можно будет использовать в LaTeX как любые другие команды, например: Документация по \PRODUCT \VERSION.

variables:
  PRODUCT: Sobiraka
  VERSION: 0.0.1

Файл стилей #

Файл style.sty определяется темой оформления и подключается до начала документа (до \begin{document}). С его помощью можно подключить необходимые пакеты LaTeX, выбрать шрифты для документа, установить глобальные параметры и определить собственные команды LaTeX.

Как правило, это самый большой небинарный файл в теме оформления LaTeX.

С помощью настройки latex.header можно указать файл с дополнительными командами LaTeX, необходимыми для конкретного документа. Эти команды вставляются после содержимого файла стилей, но тоже до конструкции \begin{document}.

Обложка #

Файл cover.tex обычно используется для создания обложки документа.

В проектах из нескольких документов используйте переменную \TITLE, чтобы подставить на обложку каждого PDF-файла нужное название.

Оглавление #

Файл toc.tex обычно используется для генерации оглавления средствами LaTeX.

Плагин для обработки страниц #

В файле extension.py может быть определён обработчик страниц — код на Python для дополнительной обработки содержимого перед рендерингом.

Класс плагина должен наследоваться от класса LatexProcessor. Плагин имеет почти неограниченные возможности в рамках обработки отдельной страницы, см. API для обработчиков.

Собирака содержит вспомогательные классы для работы с LaTeX-пакетами minted и tabularray. Чтобы использовать возможности, предоставляемые этими классами, добавьте их в качестве базовых наравне с LatexProcessor. Подробнее читайте в исходном коде Собираки.