- PVSM.RU - https://www.pvsm.ru -
Когда мы полтора года назад внедряли у себя генератор документаций Sphinx, перед нами стояла задача генерировать PDF. Дело оказалось весьма непростое. Готовых инструкций “бери и делай” на ресурсах не было. Мы пошли методом проб и ошибок. Через 3 дня мучений мы умели генерить PDF с нужным нам оформлением.
Сделали и забыли — работает же. Пока не случилась проблема со шрифтами. Снова намучились и снова решили. Но что примечательно — с тех пор готовой инструкции по генерации в PDF на просторах интернета не появилось. Поэтому выкладываю нашу. Внутри алгоритм с комментариями и файлами шаблона, особенностями ReST для LaTeX, которые мы собрали опытным путём.
Статья для тех, кто уже использует Sphinx, но имеет проблемы с LaTeX или PDF. Если вы только рассматривает Sphinx как инструмент документирования, будет полезно представлять, как готовить и подавать документацию в этих форматах.
Сразу скажу, почему нам не подошёл ReadTheDocs, где уже предусмотрена генерация PDF:
Для простейшего PDF подойдёт rst2pdf [1]. Но нам не подойдет простейший PDF, потому что нужно делать по красоте, использовать стилизованные шаблоны. Поэтому используем LaTeX, как промежуточный формат.
Он позволяет решить массу вопросов с нумерацией страниц, оглавлением, типографикой, переносом слов, сносками, таблицами, перекрестными ссылками, иллюстрациями и т.д. Структуру документа в LaTeX можно отдельно стилизовать, одна и та же структура данных может выводиться в разных форматах, с различным оформлением. Это управляется стилями LaTeX.
Стилизованные PDF нам нужны для формирования выходной документации для клиента: пользовательских инструкций, отчетов, коммерческих предложений, простых презентаций.
Спасибо Андрею Безрукову (@aur [2]), который собрал первичную информацию и проверил базовые вещи.
Python и Sphinx уже должны стоять на сервере (у нас Debian), подготовлена документация в reStructuredText, генерация которой проверена на формате html.
Ставим пакеты для LaTeX. Пример:
sudo apt-get install texmaker gummi texlive texlive-full texlive-latex-recommended latexdraw intltool-debian lacheck libgtksourceview2.0-0 libgtksourceview2.0-common lmodern luatex po-debconf tex-common texlive-binaries texlive-extra-utils texlive-latex-base texlive-latex-base-doc texlive-luatex texlive-xetex texlive-lang-cyrillic texlive-fonts-extra texlive-science texlive-latex-extra texlive-pstricks
В конфиге документации conf.py добавляем/раскомменитруем параметр latex_documents:
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, documentclass [howto/manual]).
latex_documents = [
('index', 'yourdoc.tex', u'DocName', u'YourName', 'manual'),
]
Здесь же находятся другие основные настройки для LaTeX: размер страницы, шрифт, преамбула и т.д.
Выполняем команду:
sphinx-build -b latex doc/source/ doc/latex/
где source — это папка с корневым файлом index.rst, а latex — папка назначения.
Генерируется сразу вся документация, а не отдельные файлы. В результате в корне папки latex появится пачка файлов, среди которых файл .tex — главный файл документации в формате latex. Пример содержимого папки на этом этапе в архиве latex_default.zip.
Если нужно изменить базовую верстку LaTeX, и основных настроек в conf.py недостаточно, меняем сам шаблон документа, его разметку и стили.
В файле .tex есть преамбула (до begin{document}), где подключаются пакеты, определяются переменные, могут описываться стили и т.д. Здесь подключаем дополнительные пакеты, которые нам нужны.
Примеры
usepackage{multicol}
usepackage{tikz}
usepackage[screen,margin=0.8in]{geometry}
usepackage{geometry}
geometry{landscape}
В файле .tex находится директива maketitle, которая создаёт стандартный титульный лист, используя информацию о названии документа (title), авторе (author) и дате написания текста (date).
Можем заменить maketitle на свой шаблон. Мы для себя создали отдельный файл TitlePage.tex — шаблон главной страницы, на который заменяем maketitle. Для разных документов используем различные шаблоны оформления.
Примеры
tableofcontents
phantomsectionlabel{index::doc}
noindent Copyright copyright [COPYRIGHT]\
noindent textsc{[COPYRIGHT_2]}\ % Publisher
noindent textsc{url{https://netoria.ru}}\ % URL
noindent [RIGHT_INFO] \ % License information
noindent textit{Дата публикации: [DOC_DAY]}
newpage
где [COPYRIGHT], [RIGHT_INFO] и пр. заменяем на нужный контент.
В конец .tex-файла тоже можно добавить какой-либо шаблон-завершение. Так мы вставляем свой лого и контакты, а иногда и внешний PDF-файл рекламного характера.
newpage
textcolor{red}{noindentmakebox[linewidth]{rule{textwidth}{0.4pt}}}parvspace{0.5cm}
begin{figure}[h]
begin{center}
begin{minipage}[h]{0.3linewidth}
includegraphics[width=0.8linewidth]{logo_contact.png}
end{minipage}
hfill
begin{minipage}[h]{0.6linewidth}
{ООО Нетория}par{+7 (3452) 692-242}par{netoria.ru}par{info@netoria.ru}
end{minipage}
end{center}
end{figure}
parvspace{0.5cm}
textcolor{red}{noindentmakebox[linewidth]{rule{textwidth}{0.4pt}}}
includepdf[pages={1,2}]{advertising.pdf}
renewcommand{indexname}{Алфавитный указатель}
printindex
end{document}
Копируем в папку latex наш логотип logo.png, т.к. он используется у нас в шаблоне титульной страницы.
Выполняем первую генерацию документа PDF командой:
pdflatex yourdoc.tex
В папке latex появляются файлы:
Выполняем генерацию и стилизацию оглавления командой:
makeindex yourdoc.idx
Выполняем повторную и финальную генерацию PDF:
pdflatex yourdoc.tex
В той же папке появляется финальный файл PDF. Пример содержимого папки на этом этапе в архиве latex_modified.zip.
Если не проделывать промежуточных генераций, то на выходе будет документ без оглавления. Оглавление toctree корневого файла становится оглавлением книги PDF. Оглавление contents каждого из файлов становится оглавлением каждой главы. Все ссылки оглавления, внутренние и внешние ссылки ReST корректно переносятся.
Если в ReST есть ошибки (отсутствуют изображения, некорректный синтаксис и подобное) — то при генерации PDF команда pdflatex тоже будет выдавать ошибки и ожидать действий пользователя (Enter — пропустить и продолжить, H — исправить автоматически, X — оборвать генерацию). Чтобы отключить этот интерактив, команду нужно вызвать с параметром, который оборвет процесс при первой же ошибке:
pdflatex -halt-on-error yourdoc.tex
Для html версии эти требования являются некритичным, документация всё равно будет сформирована. Но для LaTeX это фатально. Список собран опытным путём.
Ещё, иногда страницы разбиваются неадекватно, если есть картинки, таблицы, блоки предупреждений. Тогда в файле rst придётся расставлять разрыв страницы для latex:
.. raw:: latex
newpage
При возникновении проблемы первым делом смотрите логи — причины могут быть разными. У нас было 2 ситуации. Добавляйте в комментариях свои.
В один прекрасный день перестала работать генерация. Связали это с обновлением сервера. Посмотрели логи — sphinx стал искать шрифты в другой папке. Решили через mount папки шрифтов, прописал это в автозагрузке сервера.
Другой случай. Для LaTeX нужны шрифты в формате tfm. При установке шрифтов на сервер они должны генериться автоматически. Почему-то это работает не всегда. Решили это ручным запуском генерации (команда mktextfm <название шрифта>) для таких шрифтов.
Надеюсь, это поможет вам сэкономить несколько часов или дней при решении подобной задачи.
Об ошибках прошу сообщать в личку.
Автор: Елена Василенко
Источник [8]
Сайт-источник PVSM.RU: https://www.pvsm.ru
Путь до страницы источника: https://www.pvsm.ru/pdf/254697
Ссылки в тексте:
[1] rst2pdf: https://github.com/rst2pdf/rst2pdf
[2] @aur: https://habrahabr.ru/users/aur/
[3] так: https://github.com/sphinx-doc/sphinx/issues/777#issuecomment-255660678
[4] Демо_генерации_PDF.tar.gz: https://yadi.sk/d/FiCX3cDB3HqD6g
[5] latex_default.zip: https://yadi.sk/d/FGPguvfd3HqDC8
[6] latex_modified.zip: https://yadi.sk/d/3ALpw_f93HqDD5
[7] www.latextemplates.com: http://www.latextemplates.com/
[8] Источник: https://habrahabr.ru/post/328182/?utm_source=habrahabr&utm_medium=rss&utm_campaign=best
Нажмите здесь для печати.