documentation-maven-plugin-reactor

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

License

License

Categories

Categories

Maven Build Tools React User Interface Web Frameworks Reactor Container Microservices Reactive libraries
GroupId

GroupId

io.github.tobiashochguertel
ArtifactId

ArtifactId

documentation-maven-plugin-reactor
Last Version

Last Version

0.0.10
Release Date

Release Date

Type

Type

pom
Description

Description

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

Project URL

https://github.com/tobiashochguertel/documentation-maven-plugin
Project Organization

Project Organization

Tobias Hochgürtel
Source Code Management

Source Code Management

https://github.com/tobiashochguertel/documentation-maven-plugin/tree/master

Download documentation-maven-plugin-reactor

How to add to project

<!-- 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>
// https://jarcasting.com/artifacts/io.github.tobiashochguertel/documentation-maven-plugin-reactor/
implementation 'io.github.tobiashochguertel:documentation-maven-plugin-reactor:0.0.10'
// https://jarcasting.com/artifacts/io.github.tobiashochguertel/documentation-maven-plugin-reactor/
implementation ("io.github.tobiashochguertel:documentation-maven-plugin-reactor:0.0.10")
'io.github.tobiashochguertel:documentation-maven-plugin-reactor:pom:0.0.10'
<dependency org="io.github.tobiashochguertel" name="documentation-maven-plugin-reactor" rev="0.0.10">
  <artifact name="documentation-maven-plugin-reactor" type="pom" />
</dependency>
@Grapes(
@Grab(group='io.github.tobiashochguertel', module='documentation-maven-plugin-reactor', version='0.0.10')
)
libraryDependencies += "io.github.tobiashochguertel" % "documentation-maven-plugin-reactor" % "0.0.10"
[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

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>

Versions

Version
0.0.10