documentation-maven-plugin-reactor

Maven-build plugin which helps me to generate the documentation (document) via docs-as-source via doctoolchain.

License	Apache License, Version 2.0
Categories	Maven Build Tools React User Interface Web Frameworks Reactor Container Microservices Reactive libraries
GroupId	io.github.tobiashochguertel
ArtifactId	documentation-maven-plugin-reactor
Last Version	0.0.10
Release Date	May 7, 2018
Type	pom
Description	documentation-maven-plugin-reactor Maven-build plugin which helps me to generate the documentation (document) via docs-as-source via doctoolchain.
Project URL	https://github.com/tobiashochguertel/documentation-maven-plugin
Project Organization	Tobias Hochgürtel
Source Code Management	https://github.com/tobiashochguertel/documentation-maven-plugin/tree/master

Download documentation-maven-plugin-reactor

Filename	Size
documentation-maven-plugin-reactor-0.0.10.pom	7 KB

How to add to project

Apache Maven

<!-- https://jarcasting.com/artifacts/io.github.tobiashochguertel/documentation-maven-plugin-reactor/ -->
<dependency>
    <groupId>io.github.tobiashochguertel</groupId>
    <artifactId>documentation-maven-plugin-reactor</artifactId>
    <version>0.0.10</version>
    <type>pom</type>
</dependency>

Gradle Groovy

// https://jarcasting.com/artifacts/io.github.tobiashochguertel/documentation-maven-plugin-reactor/
implementation 'io.github.tobiashochguertel:documentation-maven-plugin-reactor:0.0.10'

Gradle Kotlin

// https://jarcasting.com/artifacts/io.github.tobiashochguertel/documentation-maven-plugin-reactor/
implementation ("io.github.tobiashochguertel:documentation-maven-plugin-reactor:0.0.10")

Apache Buildr

'io.github.tobiashochguertel:documentation-maven-plugin-reactor:pom:0.0.10'

Apache Ivy

<dependency org="io.github.tobiashochguertel" name="documentation-maven-plugin-reactor" rev="0.0.10">
  <artifact name="documentation-maven-plugin-reactor" type="pom" />
</dependency>

Groovy Grape

@Grapes(
@Grab(group='io.github.tobiashochguertel', module='documentation-maven-plugin-reactor', version='0.0.10')
)

Scala SBT

libraryDependencies += "io.github.tobiashochguertel" % "documentation-maven-plugin-reactor" % "0.0.10"

Leiningen

[io.github.tobiashochguertel/documentation-maven-plugin-reactor "0.0.10"]

Dependencies

There are no dependencies for this project. It is a standalone project that does not depend on any other jars.

Project Modules

• documentation-maven-plugin
• demo-reuse-of-doc-concept

Overview

This is a maven build plugin which helps me to generate the documentation of my projects. In my projects the final documentation ( document ) is an aggregated documentation from several additional documents. Additional documents are common generated via an external command, by an maven build step or are provided on other ways. These steps to provide the additional documentations has to be done before the final document is created, to referential include content from them.

When all additional documents are in place the final documentation can be created.

An example for an additional document which gets included into the final documentation is the API-Guide which is builded via Spring REST Docs in the intregration-test phase. Spring REST Docs creates auto-generated snippets files (asciidoc) from integrations-tests run (Spring MVC, or RestAssured, or other REST-Testing Frameworks) which describe how-to-use my projects RESTful API by providing the necessary informations like a curl command-line example, header fields, content-type and so on.

Short

Simple way to kick-start documentation in your project without complexity (no pom-inheritance, just to add documentation-maven-plugin build plugin) which combines doctoolchain, spring-rest-docs and asciidoctor documents in the build process to an documentation. It enabled developers to write docs-as-code.

Why a maven-plugin?

Because I wanted to hold the effort as low as possible to activate writing of documentation in a software project. And I want to quick way to attach the solution to existing projects without fear.

As an plugin which does all the configuration and handling of dependecies makes the implementation of the documentation concept more resilience. With this plugin the build of the documentation is nearly standalone, decoupled from the rest of the project’s pom.xml and everything what relates to building the documentation is within (strong cohesion).

Dependencies

• doctoolchain (my fork of https://github.com/docToolchain with improvements)

• drawio-batch Command line converter for draw.io diagrams

A few words about my fork of doctoolchain:

• Includes spring-rest-docs dependency to provide the asciidoctor macros from spring-rest-docs in doctoolchains build process

• Fixes a Issue a chained maven and gradle build.

The problem was that when doctoolchain build the final documentation it uses the spring-rest-docs provided asciidoctor macros, these macros use the gradle-build snippet directory-path which is build/generated-snippets but the snippets are already generated from maven and stored in maven’s target directory target/generated-snippets/.

I add a System.setProperty("maven.home", "/usr/local/Cellar/maven/3.5.3/libexec") in scripts/AsciiDocBasics.gradle of doctoolchain to tell spring-rest-docs that it should use the maven snippet path.

How to use

Snapshots are available at OSS Sonatype Snapshot Repository: documentation-maven-plugin Snapshots Releases are available at Maven Central Repository: packages with groupid: io.github.tobiashochguertel at search.maven.org

pom.xml usage example:

<build>
    <plugins>
    <!-- ... -->
        <plugin>
            <groupId>io.github.tobiashochguertel</groupId>
            <artifactId>documentation-maven-plugin</artifactId>
            <version>0.0.10</version>
            <executions>
                <execution>
                    <id>arc42</id>
                    <phase>verify</phase>
                    <goals>
                        <goal>htmldocument</goal>
                    </goals>
                    <configuration>
                        <docDir>${basedir}/target/docs/arc42</docDir>
                        <docsOutputDirectory>${basedir}/target/docs/arc42</docsOutputDirectory>
                        <docsInputDirectory>${basedir}/src/main/docs/arc42</docsInputDirectory>
                        <drawioDocDir>${basedir}/target/docs/arc42/images/drawio-diagrams</drawioDocDir>
                    </configuration>
                </execution>
                <execution>
                    <id>api-guide</id>
                    <phase>verify</phase>
                    <goals>
                        <goal>htmldocument</goal>
                    </goals>
                    <configuration>
                        <docDir>${basedir}/target/docs/api-guide</docDir>
                        <docsOutputDirectory>${basedir}/target/docs/api-guide</docsOutputDirectory>
                        <docsInputDirectory>${basedir}/src/main/docs/api-guide</docsInputDirectory>
                        <drawioDocDir>${basedir}/target/docs/api-guide/images/drawio-diagrams</drawioDocDir>
                    </configuration>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

Helpfully resources:

Asciidoctor

• Asciidoctor User Manual

• AsciiDoc Syntax Quick Reference

• POWERMAN - AsciiDoc cheatsheet

docToolchain

• docToolchain Manual

Spring-REST-Docs

• Spring-Rest-Docs issue Is there an way to create the api-guide from commandline with asciidoctor?

• Spring REST Docs

Versions

Version
0.0.10 May 7, 2018