CourseOrchestra / course-doc

Templates for creating asciidoctor documentation

Шаблоны документации КУРС

Warning

Сведения в документе устарели. Для получения pdf-файла мы разработали проект https://github.com/CourseOrchestra/asciidoctor-open-document .

Краткое описание

В папке doc приведен шаблон — расширение для DocBook XSL, — обеспечивающий конвертацию docbook-файла в pdf через xsl-fo. Основан на шаблоне, который поставляется вместе с AsciidocFX.

Вариант в меру громоздкий и не очень удобен для кастомизации, но альтернативы пока не понятны.

Использование совместно с AsciidocFX

Для использования функции экспорта в pdf при помощи редактора AsciidocFX скачайте это приложение и установите его. Далее в папке установки перейдите в conf\docbook-config и замените файлы fo-pdf.xsl и common.xsl на соответствующие файлы, содержащиеся в папке template/docbook-xsl репозитория.

В папке doc репозитория находится файл db_template_examples.adoc, содержащий описание всех возможных вариантов использования шаблона c примерами. Сохраните папку doc на диске и экспортируйте его в pdf при помощи AsciidocFX.

Использование для автоматической сборки

Для автоматической сборки используйте проект asciicotor-fopub.

Если нужны скрипты, которые мы используем для сборки документации, поднимите Issue, выложим их в отдельную папку.

Альтернативные варианты

1. https://github.com/Mogztter/asciidoctor-web-pdf [Asciidoctor Web PDF]. Лучшая альтернатива, если достаточно фич. Позволяет генерировать pdf через html с использованием спецификаций W3C Paged Media и Generated Content for Paged Media.

2. Asciidoctor PDF. Самый простой вариант, т.к. позволяет осуществлять конвертацию напрямую из asciidoc-формата. Однако на текущий момент обладает рядом ограничений, которые не позволяют пока его использовать для нашей отчетной документации. Эти ограничения потихоньку снимаются и есть надежда, что все-таки это проект будет доведен до требуемого состояния.

3. Dblatex. Это довольно старый и отработанный проект. Однако он работает на второй версии питона и требует довольно больших усилий для запуска и настройки.

4. Asciidoctor LaTeX. Проект, который не развивается. Не понятно что делает, то ли TeX интегрирует в Asciidoctor, то ли Asciidoctor конвертирует в TeX. Были какие-то разговоры, что будет отдельный проект по конвертации в TeX, но ничего не видно.