JarCastingOverview
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
<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>