Основная документация по сайту: Maven 3

Документация для разработчиков программного обеспечения — это документы, которые описывают, как запустить или использовать артефакт / проект. Обычно документация предоставляет любые выставленные настройки, их использование и значения по умолчанию. Кроме того, информация об интеграции, точках входа и выхода, таких как JMS-очереди, JMX MBeans, объекты DataSource и / или переменные JNDI для запуска и использования артефакта. Существует множество программ и стандартов для подготовки документации такого уровня, в том числе MS Word , Sharepoint, Doxygen , Latex , Wiki , Markdown , Текстиль и т. Д.

За пределами артефактов руководители групп документации, архитекторы и менеджеры проектов обычно просят включить JavaDocs. JavaDocs, в сочетании с Maven, предоставляет больше документации для вашей IDE и лучшую информацию для потребителей вашего артефакта. Другая важная документация включает отчеты о тестировании, покрытие тестами, инструменты статического анализа, зависимости вашего артефакта, журнал изменений и управление проблемами, например Jira или Bugzilla.

Зачем создавать документы?

Лучшая причина позаботиться о документации — это предоставить информацию для внешних разработчиков и членов команды за пределами среды разработки проекта. Документация может быть использована и внутри IDE, и, если честно, сколько раз вы хотели, чтобы у вас были источники и / или JavaDocs для зависимости, когда вы программировали, или для отправки электронного письма с документами сайта, чтобы кто-то мог быть самообслуживаемым вместо того, чтобы не торопиться.

Проблемы с традиционной документацией

Самая большая претензия к традиционной документации заключается в том, что она со временем становится устаревшей. В проекте ^{и кинжале} никогда не выделяется время на предоставление или обновление документации, а устаревшие документы могут привести разработчика или команду к ошибочному пути, ведущему к часам или дням дезинформации, ведущей к кроличьим норам.

^{† Гибкие процессы, процессы SCRUM и Lean должны дать время для обработки технического долга, такого как документация, даже если бы он назывался «необходимым злом». Узнайте больше здесь}

Во-вторых, разработчики — это те, кого

просят
принудительно поддерживать документацию, и, как правило, разработчики не очень хороши в отделе написания, и если сегменты процесса документации не автоматизированы, разработчики — это люди, и мы забываем.

Последняя серьезная проблема с традиционной документацией заключается в том, что она, как правило, не автоматизирована и является дополнительным шагом в цикле сборки / выпуска. Любой процесс в цикле сборки, который не автоматизирован и не протестирован, в какой-то момент сломается. Люди хороши в абстрактном мышлении, а не в повторяющихся процессах.

Решение проблем

Как указывалось выше, основными проблемами являются разработчики, ведущие всю документацию и документацию, которая либо построена вне непосредственной среды, либо не автоматизирована. Вот где появляется документация по сайту Maven. Maven был создан с пониманием того, что документация должна быть автоматизирована, и он постепенно улучшался в процессе обновления проекта maven.

Наиболее распространенным случаем документации сайта Maven является развертывание сгенерированной документации на внешний веб-сервер через SCP, FTP, WebDAV или SFTP. Плагин сайта использует библиотеку Apache Wagon для безопасной передачи документов. Большую часть времени документы сайта генерируются на этапах выпуска † или развертывания и генерируются на этапе проверки .

^{† Релиз не является этапом в Maven, это плагин, но это считается лучшей практикой при публикации версионных артефактов в репозиторий Maven.}

Maven 3 против Maven 2

Maven решил изменить способ сбора и генерации отчетов между выпусками Maven 2 и Maven 3. В Maven 2 POM будет иметь раздел с именем «reports <», где будут обрабатываться плагины, которые обрабатывают ReportSet . В Maven 3 теперь есть плагин, который обрабатывает и сортирует наборы отчетов, а не Maven. Плагин называется maven-project-info-reports-plugin и документацию можно найти здесь .

Источники для этой серии постов в блоге

Я предоставил ссылку на полностью функциональный мультимодульный проект maven, который публикует на http://mike-ensor.github.com/multi-module-site-doc-project/index.html и локально на $ {env. HOME} / sitedocs / $ {project.artifactId}.

https://github.com/mike-ensor/multi-module-site-doc-project .

Maven 3 Site Docs

Есть два важных элемента в отношении документации сайта для Maven. Плагины, которые генерируют элементы ReportSet и Site Doc / Descriptors.

Плагины

Плагины являются важной частью процесса документирования и обычно выполняются на протяжении всего жизненного цикла сборки maven, генерируя артефакты для фазы плагина, которая генерирует ReportSet. Хорошим примером будет плагин maven-checkstyle-plugin. Плагин, как правило, связан с фазами ресурсов процесса или пакета, поэтому разработчики знают, что в начале жизненного цикла сборки имело место нарушение контрольного стиля. Плагин генерирует документ checkstyle.xml, который затем используется на фазе сайта плагином maven-project-info-reports-plugin для создания страницы отчета в стиле checkstyle.

Maven Site Plugin

Плагин maven-site-plugin — это основной плагин, который используется для хранения всей документации сайта. Каждый плагин, который создает и / или использует ReportSet, должен быть настроен внутри раздела <reportPlugins>. ПРИМЕЧАНИЕ: это где плагин Wagon установлен как зависимость. Плагин Site будет использовать строку <distributionManagement> <site>, чтобы определить, где будут публиковаться документы сайта (SCM, WebDAV, SFTP и т. Д.).

<plugin>
 <artifactId>maven-site-plugin</artifactId>
 <version>${plugin.maven-site.version}</version>
 <dependencies>
  <dependency><!-- add support for ssh/scp -->
   <groupId>org.apache.maven.wagon</groupId>
   <artifactId>wagon-ssh</artifactId>
   <version>${plugin.wagon-ssh.version}</version>
  </dependency>
 </dependencies>
 <configuration>
  <attach>true</attach>
  <reportPlugins>
   <plugin>
   ...
   ... Plugins go here
   ....
   </plugin>
  </reportPlugins>
  <attach>true</attach>
 </configuration>
</plugin>

Плагин Maven Project Info Report

Плагин maven-project-info-report-plugin — это основной плагин, который используется плагином maven-site-plugin, который Maven 3 использует для сопоставления и создания общих документов отчетов о сайте для артефакта.

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-project-info-reports-plugin</artifactId>
    <configuration>
        <dependencyDetailsEnabled>false</dependencyDetailsEnabled>
        <dependencyLocationsEnabled>false</dependencyLocationsEnabled>
    </configuration>
    <!-- simpler configuration without
        reportSets available for usual cases -->
    <!-- distribution-management,
        index, dependencies, help,
        issue-tracking, plugins,
        cim, license, dependency-management,
        mailing-list, project-team,
        dependency-convergence,
        scm, plugin-management,
        modules, summary -->
    <reports>
        <report>summary</report>
        <report>dependencies</report>
        <report>project-team</report>
        <report>issue-tracking</report>
        <report>scm</report>
        <report>cim</report>
        <report>modules</report>
        <report>plugins</report>
    </reports>
</plugin>

Кратко рассмотрим типы отчетов, которые автоматически создаются с помощью плагина maven-project-info-reports-plugin. Многие из этих автоматически генерируемых отчетов предоставляют дополнительную информацию поверх избыточной информации, предоставляемой перечисленными ниже плагинами.

Список автоматически предоставляемых отчетов

• распределение, управление
• показатель
• зависимости
• Помогите
• проблема отслеживания
• плагины
• МГК
• лицензия
• зависимость-менеджмент
• список рассылки
• проектная группа
• Зависимость-схождение
• СКМ
• плагин-менеджмент
• модули
• резюме

Общие плагины

<plugin>
 <groupId>org.apache.maven.plugins</groupId>
 <artifactId>maven-checkstyle-plugin</artifactId>
 <configuration>
  <skip>${checkstyle.skip}</skip>
  <configLocation>${checkstyle.configUrl}</configLocation>
  <failsOnError>false</failsOnError>
  <enableRulesSummary>true</enableRulesSummary>
  <includeTestSourceDirectory>true</includeTestSourceDirectory>
 </configuration>
</plugin>

<plugin>
 <groupId>org.codehaus.mojo</groupId>
 <artifactId>findbugs-maven-plugin</artifactId>
 <configuration>
  <skip>${findbugs.skip}</skip>
  <xmlOutput>true</xmlOutput>
 </configuration>
</plugin>

<plugin>
 <groupId>org.codehaus.mojo</groupId>
 <artifactId>cobertura-maven-plugin</artifactId>
 <configuration>
  <skip>${cobertura.skip}</skip>
 </configuration>
</plugin>

PMD и CPD — maven-pmd-plugin — обеспечивает статический анализ (PMD) и обнаружение дублирования кода / вырезание-копирование-вставка для артефакта. Узнайте больше о плагине PMD здесь .

Пример отчета о плагине

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-surefire-report-plugin</artifactId>
    <reportSets>
        <reportSet>
            <id>integration-tests</id>
            <reports>
                <report>report-only</report>
                <report>failsafe-report-only</report>
            </reports>
        </reportSet>
    </reportSets>
</plugin>

JavaDoc — maven-javadoc-plugin — Объединяет JavaDocs в структуру отчетности. ПРИМЕЧАНИЕ: это не нужно запускать во время стандартной сборки, только на этапе создания отчетов.

Пример отчета о плагине

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <configuration>
        <skip>${javadocs.skip}</skip>
        <failOnError>false</failOnError>
    </configuration>
</plugin>

JXR — maven-jx-plugin — Создает информацию о перекрестных ссылках для классов. Checkstyle, PMD, FindBugs, JavaDocs и различные другие плагины могут использовать конфигурацию JXR. ПРИМЕЧАНИЕ: этот плагин должен быть запущен на раннем этапе жизненного цикла Maven (предложить ресурсы процесса) в дополнение к разделу о плагине sitedoc.

Пример отчета о плагине

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-jxr-plugin</artifactId>
    <configuration>
        <aggregate>true</aggregate>
    </configuration>
</plugin>

Полезные плагины

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

• Taglist — ищет в исходном коде конкретные слова, такие как @TODO и FIXME, а затем объединяет их в отчет по проекту — http://mojo.codehaus.org/taglist-maven-plugin/
• Версии — использует центральное и / или локальное зеркало maven для поиска каждой зависимости, свойств проекта и версий плагинов, затем создает отчет, в котором можно обновить как мелкие, так и основные обновления — http://mojo.codehaus.org/versions-maven -plugin /
• Changelog — использует SCM, перечисленный в разделе distributionManagement, чтобы вывести простую историю для каждого файла; выводит список самых измененных файлов, лучших участников и связывает изменения с помощью веб-инструмента SCM, такого как github или web-svn — http://maven.apache.org/plugins/maven-changelog-plugin
• Изменения — интегрируется с Jira, Trac или Bugzilla (или любым changelist.xml, созданным системой управления проблемами) и отображает, какие ошибки были обновлены между текущим и предыдущим выпуском — http://maven.apache.org/plugins/maven. -изменения-плагин /

Конец первой части

Следующая статья будет посвящена части документации для разработчиков; более конкретно, охватывающий XDoc и APT. Документация сайта надежна, и в следующем посте будет показано, как программировать некоторые части документов XDoc, используя шаблоны Velocity.

Последняя часть этого блога будет посвящена многомодульным проектам. Кроме того, в этом посте будет показано, как развернуть документы сайта на страницах Github, чтобы вы могли иметь документы сайта по адресу http: // < имя пользователя > .github.com / < ваш-проект >.