Темы Sphinx PDF

Во-первых, Sphinx не генерирует вывод PDF сам по себе, хотя есть два общих метода для перехода из исходных файлов Sphinx в вывод PDF:

1. Используйте конструктор Latex, а затем отдельный инструмент, например latex2pdf, для создания вывода PDF.
2. Используйте плагин Sphinx из проекта rst2pdf

При этом существует большой потенциал для настройки стиля вывода PDF с использованием любого метода.

1. При использовании метода latex- ›pdf вы можете настроить вывод latex, используя ряд параметров в файле конфигурации sphinx. См. здесь. Однако этот метод несколько менее удобен, чем темы HTML, которые Sphinx использует для генерации HTML (IMO).
2. При использовании rst2pdf вы можете определить свою собственную таблицу стилей, которая более подробно описана в руководстве (посмотрите под заголовком Стили). rst2pdf включает несколько таблиц стилей, которые можно комбинировать для получения различных результатов. И, конечно же, вы также можете изменить их или создать свои собственные (это просто файлы JSON). Эти таблицы стилей также поддерживают своего рода наследование, поэтому действуют больше как темы Sphinx HTML, чем предыдущий метод.

Для Sphinx нет предопределенных тем для вывода PDF. Но LaTex предлагает богатый набор опций для стилизации документа. Моя проблема заключалась в том, чтобы найти правильный способ стилизовать документ с помощью сфинкса. Вот способ, который у меня сработал:

Сначала взгляните на conf.py. Там вы найдете вариант latex_elements. С помощью этой опции вы можете добавлять в вывод свои собственные команды LaTex. Например:

latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
'papersize': 'a4paper',

# The font size ('10pt', '11pt' or '12pt').
'pointsize': '12pt',

'fontpkg': r"""
\PassOptionsToPackage{bookmarksnumbered}{hyperref}

""",

# Additional stuff for the LaTeX preamble.
'preamble': r"""
\usepackage{setspace}
""",

'footer': r"""
""",

'maketitle': r'''
\pagenumbering{arabic}
''',
}

Важно знать несколько моментов.

• Используйте r""", чтобы избежать конфликтов с python
• Хотя preamble было бы правильным моментом для добавления \usepackage, вы можете конфликтовать с настройками Sphinx по умолчанию. Посмотрите на fontpkg в примере. Это первое включение в выходной документ .tex. Если вам нужно установить параметры для пакетов по умолчанию, сделайте это здесь.
• maketitle позволяет вам определять вашу собственную титульную страницу. См. Некоторую документацию по латексу. Я установил там \pagenumbering, чтобы оглавление было арабскими цифрами, поэтому реальное содержимое начинается на странице «1».

Обладая правильным знанием латексных команд, вы можете получить хорошее тематическое оформление с помощью нескольких команд. Хороший источник помощи - https://tex.stackexchange.com/, где есть решения для наиболее распространенных проблем. Но найти правильные латексные команды намного сложнее, чем выбрать тему, как это сделано для HTML.

Было бы полезно взглянуть на Tex-Output под ./_build. Здесь вы можете увидеть, как latex_elements-опции были включены в документ.