Подготовка удобочитаемой документации, которую легко поддерживать, не является тривиальной задачей и не является любимой для большинства разработчиков. У нас есть большой выбор методов для создания документации, от простых, таких как обычные текстовые файлы, до более сложных, таких как Sphinx generator . Каждый из них имеет свои преимущества и недостатки. Обычные файлы просты в обслуживании, не требуют каких-либо специальных файлов, но не подходят для современного Интернета. С другой стороны, Sphinx – это передовое решение для подготовки профессиональной документации, но для него требуются сторонние инструменты.
Для разработчиков Java, которые используют Apache Maven для создания проектов, будет удобнее всего использовать тот же инструмент для создания документации. На этапе жизненного цикла site Maven запускает плагин сайта, который генерирует документацию из исходных файлов. Вывод HTML-сайта полезен во многих случаях, но он не очень удобен для пользователя. По умолчанию исходные файлы должны быть сохранены в формате APT , хотя в настоящее время мы предпочитаем использовать Markdown или reStructuredText.
К счастью, maven-site-plugin допускает некоторую настройку, которую мы используем для создания простого сайта документации из файлов markdown. Пример проекта можно найти на Github .
HTML-шаблон
Плагин сайта Maven по умолчанию использует Шаблон Velocity , это обеспечивается Doxia (фреймворк, внутренне используемый Maven для генерации контента). Для нашей цели нам нужно что-то попроще, поэтому мы готовим новый шаблон и сохраняем его как dev-to-template.vm в src/site/ каталог.
Start
#* *#$bodyContent
Переменная $body Content ссылается на выходные данные из файлов рендеринга Markdown, которые должны быть сохранены в каталоге src/site/markdown .
Конфигурация модуля
Нам нужно настроить конфигурацию maven-site-plugin в модуле pom.xml
maven-site-plugin 3.8.2 false src/site/dev-to-template.vm false org.apache.maven.doxia doxia-module-markdown 1.9
С собственностью файл шаблона мы указываем на созданный файл шаблона. Когда плагин зависит от doxia-module-markdown , он будет искать файлы Markdown в каталоге src/site/markdown и использовать его для создания HTML-разметок.
Генерация контента запускается командой ./mvn site , а вывод HTML сохраняется в каталоге target/site/ . С помощью примера шаблона мы получаем HTML-документацию с простой навигацией. Если есть необходимость, должно быть легко добавить дополнительные настройки. Что самое главное, нам не нужны никакие дополнительные инструменты для создания контента.
Оригинал: “https://dev.to/miloszpiglas/generate-html-documentation-from-markdown-with-maven-site-plugin-4ah7”