Публикация PDF в Sphinx с помощью rst2pdf¶

Генератор документации Sphinx позволяет получить документацию в разных форматах. Самый популярный после HTML — это, пожалуй, PDF.

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

В этой статье описаны самые базовые настройки и действия, которые необходимы, чтобы получить русскоязычный PDF-документ в Sphinx через rst2pdf. За более детальной информацией обращайтесь к документации rst2pdf (https://rst2pdf.org/static/manual.pdf).

Имейте в виду, что, согласно документации, rst2pdf — расширение экспериментальное, так что будьте готовы к тому, что не все будет работать так, как хотелось бы.

Предварительные условия¶

В этой статье я предполагаю следующее:

Вы используете Windows.
У вас уже установлен Sphinx.

Если нет, установите (https://www.sphinx-doc.org/en/master/usage/installation.html).
У вас уже есть проект Sphinx, то есть набор файлов RST, конфигурационный файл conf.py и так далее.

Если нет, создайте (https://www.sphinx-doc.org/en/master/usage/quickstart.html).

Установка расширения rst2pdf в Sphinx¶

rst2pdf не является частью Sphinx по умолчанию, это расширение, которое нужно установить дополнительно.

Установите rst2pdf с помощью следующей команды:

pip install rst2pdf

Теперь расширение готово к работе.

Настройка шрифтов для русскоязычных документов¶

Для корректной публикации русскоязычных документов нужно создать файл JSON и указать в нем параметр fontsAlias со списком шрифтов, которые вы будете использовать в документации. Подробнее о настройке шрифтов читайте в документации rst2pdf.

Ниже приведен пример простейшего файла JSON.

{"fontsAlias": {"stdFont": "Arial",
                "stdBold": "Arial-Bold",
                "stdItalic": "Arial-Italic",
                "stdBoldItalic": "Arial-BoldItalic" }
}

Созданный файл рекомендуется поместить в папку _static вашего проекта Sphinx.

Параметры PDF в conf.py¶

Внесите в файл conf.py вашего проекта следующие параметры:

В extensions добавьте элемент rst2pdf.pdfbuilder.
Добавьте секцию с параметрами PDF в конец файла. Не забудьте добавить pdf_stylesheets и указать в нем имя файла JSON с параметрами шрифтов (см. предыдущий раздел).

В примере ниже приведены фрагменты файла conf.py с некоторыми параметрами публикации PDF — это те параметры, которые используются при публикации этой статьи в формат PDF. Полный список параметров вы найдете в документации rst2pdf.

# -- General configuration ------

extensions = ['rst2pdf.pdfbuilder']

# -- Options for PDF output -----

pdf_documents = [('index', 'rst2pdf-in-sphinx', '', '')]
pdf_language = "ru_RU"
pdf_stylesheets = ['styles.json']
pdf_style_path = ['_static']
pdf_use_coverpage = False
pdf_use_toc = False

В этом примере третий и четвертый элементы кортежа в pdf_documents (заголовок документа и имя автора) — пустые строки. Причина в том, что PDF-документ публикуется без обложки (параметр pdf_use_coverpage установлен в False). Заголовок документа и имя автора используются только на обложке, поэтому в данном случае они не нужны.