Когда мы полтора года назад внедряли у себя генератор документаций Sphinx, перед нами стояла задача генерировать PDF. Дело оказалось весьма непростое. Готовых инструкций “бери и делай” на ресурсах не было. Мы пошли методом проб и ошибок. Через 3 дня мучений мы умели генерить PDF с нужным нам оформлением.
Сделали и забыли — работает же. Пока не случилась проблема со шрифтами. Снова намучились и снова решили. Но что примечательно — с тех пор готовой инструкции по генерации в PDF на просторах интернета не появилось. Поэтому выкладываю нашу. Внутри алгоритм с комментариями и файлами шаблона, особенностями ReST для LaTeX, которые мы собрали опытным путём.
Статья для тех, кто уже использует Sphinx, но имеет проблемы с LaTeX или PDF. Если вы только рассматривает Sphinx как инструмент документирования, будет полезно представлять, как готовить и подавать документацию в этих форматах.
Читать полностью »