asciidoctor-lifecycle-maven-plugin

A lifecycle and custom mojos to isolate the building of asciidoctor documentation from the default lifecycle with the asciidoctor-maven-plugin.

• About this project
  • Last changes
  • What this project offers?
  • Why this project?
• Project status
• A custom lifecycle for build Asciidoctor projects
  • The lifecycle asciidoctor-lifecycle-build
• Themes
  • What is a theme?
  • How Asciidoctor Lifecycle Maven Plugin manages themes
• How to use the lifecycle
  • Configure the new lifecycle in pom.xml
  • Configure the asciidoctor-maven-plugin
  • Generate the html documents
  • Publish the generated files
  • About configuring multiple output formats
• Some examples explained in detail
  • How to use the automatically created properties
  • How to configure wagon for publishing
• How can I build the plugin?
  • Conventional build
  • Run tests in parallel
  • Measure coverage
• Warnings
• References

About this project

Last changes

In this section I will tell you the most recent changes. This section will disappear with the final release.

2020/10/08

• Added asciidoctor-prepare-resources phase before asciidoctor-theme

• Added asciidoctor-verify phase after asciidoctor-post-publish phase.

• Renamed asciidoctor-prepare-convert to asciidoctor-pre-convert.

• Renamed asciidoctor-prepare-notify to asciidoctor-pre-notify.

• Renamed asciidoctor-prepare-publish to asciidoctor-pre-publish.

• Renamed asciidoctor-prepare-theme to asciidoctor-pre-theme.

• Renamed PrepareSourcesMojo.java to CopySourcesMojo.java (and integration test related files).

• Takari tests were replaced with Integration Testing Framework.

• JUnit4 was replaced with JUnit5 and AssertJ.

• Some tests now owns their own IT class.

• Removed one ignored test (publishWithProxy) and one redundant test (publishWithoutProxy).

• Now tests can be executed in parallel with -Pparallel.

• Now jacoco execution is optional. You can enable it with -Pquality.

2020/04/23

• Files README.adoc and lifecycle.adoc updated.

• Added phases asciidoctor-prepare-notify and asciidoctor-notify.

• Renamed phase prepare-build to asciidoctor-prepare-convert.

• Renamed phase build to asciidoctor-convert.

• Renamed phase prepare-theme to asciidoctor-prepare-theme.

• Renamed phase theme to asciidoctor-theme.

• Renamed all files and examples to conform to new names.

2020/04/20

• Big redesign of UploadMojo code (now called PublishMojo).

• upload phase renamed to asciidoctor-publish.

2020/04/17

• Source code refactorization in order to support more features.

• Test code refactorization; it is more easily create a new integration test now, with the AbstractMojoIT.

2019/08/25

• Updated README.adoc to reflect Maven [3.3.9,3.6.1] versions supported.

• Updated invoker.properties files for invoker.maven.version.

• Updated pom.xml file to Maven [3.3.9,3.6.1] requirement.

2019/08/24

• Maven requirements reduced to 3.3.9.

• Apache 2 license badge in README.adoc.

• Improvements in coverage.

• Mixin the it and unit test coverage.

• Reduce number of branches in ThemeMojo.java.

2019/08/23

• Integration with coveralls.

• Some unit tests developed.

• asciidoctor-maven-plugin:process-asciidoc goal mapped to build phase.

2019/08/19

• Initial support for uploading generated files to a wagon repository. You need to configure the wagon provider in asciidoctor-lifecycle-maven-plugin dependencies.

• Documentation improved (Javadoc).

• English fixes in README.adoc (thanks to my friend Manuel Vicente, I still need your help).

2019/08/18

• Renamed the theme-download phase to theme phase, because in this phase we do other things, as unzip and create properties, and the download is done only if the artifact is not in the local repository.

• Renamed the pre-build phase to prepare-build.

• Renamed the pre-upload phase to prepare-upload.

• Added a basic support for the upload phase, the UploadMojo.

• The property names are refactorized.

• Added the Maven site (basic).

• Documentation updated.

2019/08/16

• In the theme phase for each downloaded theme, a property is created. Its value is the path where it was unzipped.

• Documentation updated.

What this project offers?

This project offers a new Maven plugin, with the following functionalities (this is a work in progress):

• A new lifecycle, designed for resolving some of the needs I’ve found in my personal projects.

• A mojo for downloading themes for using with Asciidoctor Maven Plugin.

• A mojo for publish generated files with the help of Maven Wagon API, in the same way as the maven-site-plugin.

I hope this plugin helps others to write a cleaner separation between the build of the asciidoc documentation

Why this project?

This project tries to cover those aspects of asciidoctor-maven-plugin that doesn’t fit well with the Maven default lifecycle. What are this aspects?

• When a project contains asciidoc documentation and code, you need a complicated configuration to build only asciidoc or only code. Profiles here may be a solution, specifying modules to build in every one, but…​

• The default lifecycle seems oriented to code building; this is not something negative in itself, but the name of the phases are confusing enough if we think about documentation and not code (compile, test, verify).

• If you want to build the site documentation, Maven offers you another lifecycle: the site lifecycle.

• If you need to download a theme for generating a pdf (for example) you need to use the dependency:get as a solution, and if you need to do something more with the theme content you need to write too much configuration.

So, why not develop a custom lifecycle?

Project status

This project is a Work In Progress, in early stage of development. You can test or use it in your own projects, but you should understand:

1. Something can change at any time before the first release, breaking compatibility with pre releases versions.

2. There is no version available in any repository yet.

3. You have to build it with your own hands (it is not difficult, it is a standard Maven project).

A custom lifecycle for build Asciidoctor projects

The lifecycle asciidoctor-lifecycle-build

This lifecycle add a defined sequence of phases that helps to build the Asciidoctor documents without the use of profiles. These are the phases of this lifecycle (in sequential order):

Phase	Description	Mojo
asciidoctor-pre-theme	Prepare the theme download.
asciidoctor-theme	In this phase the themes are downloaded from remote repositories, if required, unzipped and copying common resources to a folder.	ThemeMojo
asciidoctor-pre-convert	Actions required before the asciidoctor conversion.
asciidoctor-convert	The process-asciidoc is attached to this phase, to build the documentation.
asciidoctor-pre-publish	Actions required before publishing documents.
asciidoctor-publish	Publishing generated content in a remote webdav server, a local filesystem…​	PublishMojo
asciidoctor-pre-notice	Actions required before notifying users new documentation version.
asciidoctor-notice	Actions required for notifying users new documentation version.

Themes

What is a theme?

At the moment a theme in asciidoctor-lifecycle is only an artifact wich zip packaging. This requirement allow us uncompress its contents to a folder.

At the moment it has not been formally defined or its contents established.

How Asciidoctor Lifecycle Maven Plugin manages themes

You can define the use of a theme (downloading and unpacking it to a directory) as part of the asciidoctor-lifecycle-maven-plugin configuration. You can configure so many themes as you desire.

The themes are expressed as Maven coordinates as:

<groupId>:<artifactId>[:<extension>[:<classifier>]]:<version>

So a valid theme expression is:

groupId:artifactId:zip:3.3.3

The Asciidoctor Lifecycle Maven Pluging does the following operations for every configured theme:

1. Tries to download the artifact (theme).

2. Tries to unzip the contents of the artifact downloaded to a directory, specified by the configuration property asciidoctor.lifecycle.outputDirectory as parent directory, and the directory child name is the same as its artifactId.

3. Creates a property with the value of the path of the directory where the theme was unzipped.

4. If any of the previous operations fails, it breaks the build.

All these operations are done at theme phase, so using the Asciidoctor Lifecycle you can use in the rest of the phases the property created automatically at this phase.

How to use the lifecycle

Configure the new lifecycle in pom.xml

It is very easy use this new lifecycle. It is a standard Maven plugin.

<plugin>
    <groupId>com.coutemeier.maven.plugins</groupId>
    <artifactId>asciidoctor-lifecycle-maven-plugin</artifactId>
    <version>1.0-SNAPSHOT</version>
    <extensions>true</extensions> <!--(1)-->
</plugin>

1. We use the plugin as an extension.

Configure the asciidoctor-maven-plugin

We configure the asciidoctor-maven-plugin attaching the process-asciidoc goal to the build phase.

<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>1.5.8</version>
    <executions>
    <!-- So many executions as you need -->
        <execution>
            <id>output-html</id>
            <phase>build</phase> <!--(1)-->
            <goals>
                <goal>process-asciidoc</goal>
            </goals>
            <configuration>
                <backend>html5</backend>
            </configuration>
        </execution>
    </executions>
</plugin>

1. We attach the asciidoctor-maven-plugin:process-asciidoc goal to the build phase of the asciidoctor-lifecycle-build lifecycle.

We are ready to generate our documentation separate of the normal build of our code.

Generate the html documents

mvn build

Publish the generated files

At this moment the asciidoctor-publish phase is implemented in its basic functionality. It uses the Maven Wagon API, so you have to configure the dependency to the implementation provider (if needed).

I’ve tested it to publish files to a webdav server and to copy them to a directory in filesystem, and it is possible that works with another wagon providers.

With last changes proxy feature was implemented as in maven-site-plugin.

This is a simple example to configure the upload to a directory in your filesystem:

<plugin>
    <groupId>com.coutemeier.maven.plugins</groupId>
    <artifactId>asciidoctor-lifecycle-maven-plugin</artifactId>
    <version>1.0-SNAPSHOT</version>
    <extensions>true</extensions>
    <configuration>
        <serverId>nexus</serverId> <!--(1)-->
        <publishToRepository>dav://http://my-own-webdav-server/file-repository</publishToRepository> <!--(2)-->
        <publishToRepository>file://${project.build.directory}/file-repository</publishToRepository> <!--(2)-->
        <publishToDirectory>${project.artifactId}/${project.version}</publishToDirectory> <!--(3)-->
    </configuration>
    <!-- No dependency needed -->
</plugin>

1. server identifier in settings.xml for authorization.

2. The base path for storing the files in http webdav server or filesystem (choose one).

3. The directory in the base path where you want to store the files.

If ${project.artifactId} = theArtifact and ${project.version} = 1.0.0 then generated files will be copied to `${project.build.directory}/file-repository/theArtifact/1.0.0`directory.

mvn asciidoctor-publish

About configuring multiple output formats

⚠️	The asciidoctor-maven-plugin:process-asciidoc is mapped to the build phase of this lifecycle, and it causes the execution associated with the default configuration.

Therefore, if you follow the convention of writing a shared configuration in the plugin configuration, and an execution for each of the output formats, you will also obtain the default format established by the plugin, which at the time of writing this documentation is docbook.

To avoid this additional execution you can write the corresponding one of the executions in the plugin configuration, together with the shared configuration, and the other formats in the configuration of their corresponding executors.

If you follows the shared configuration convention you will write something similar to:

<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>${asciidoctor.maven.plugin.version}</version>
    <configuration> <!--(1)-->
        <sourceDirectory>src/docs/asciidoc</sourceDirectory>
        <sourceHighlighter>coderay</sourceHighlighter>
        <attributes>
            <!--  Shared attributes-->
            <sourcedir>${project.build.sourceDirectory}</sourcedir>
            <project-version>${project.version}</project-version>
            <imagesdir>./images</imagesdir>
            <icons>font</icons>
        </attributes>
    </configuration>
    <executions>
        <execution>
            <id>generate-html5-doc</id> <!--(2)-->
            <phase>build</phase>
            <goals>
                <goal>process-asciidoc</goal>
            </goals>
            <configuration>
                <backend>html5</backend>
                <attributes>
                    <docinfo1>true</docinfo1>
                    <idprefix/>
                    <idseparator>-</idseparator>
                    <sectanchors>true</sectanchors>
                    <toc>left</toc>
                </attributes>
            </configuration>
        </execution>
        <execution>
            <id>generate-pdf-doc</id> <!--(3)-->
            <phase>build</phase>
            <goals>
                <goal>process-asciidoc</goal>
            </goals>
            <configuration>
                <backend>pdf</backend>
                <attributes>
                    <idprefix/>
                    <idseparator>-</idseparator>
                    <pagenums/>
                    <toc/>
                    <sectanchors>false</sectanchors>
                </attributes>
            </configuration>
        </execution>
    </executions>
</plugin>

1. Shared configuration at plugin configuration.

2. Configuration for HTML5 output format at its own execution configuration.

3. Configuration for PDF output format at its own execution configuration.

When executing mvn build it will also launch the execution associated with the configuration of the plugin, associated with backend = docbook.

💡	Of course, you can continue to configure the plugin in this way if you wish.

If you want to avoid the default backend generation:

Below we show you how to configure the asciidoctor-maven-plugin plugin to use it in conjunction with asciidoctor-lifecycle-maven-plugin and avoid additional backend generation by default.

<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>${asciidoctor.maven.plugin.version}</version>
    <configuration>
        <!-- Shared configuration -->
        <sourceDirectory>src/docs/asciidoc</sourceDirectory> <!--(1)-->
        <sourceHighlighter>coderay</sourceHighlighter> <!--(1)-->
        <!-- Specificy HTML5 configuration -->
        <backend>html5</backend> <!--(2)-->
        <attributes>
            <!--  Shared attributes-->
            <sourcedir>${project.build.sourceDirectory}</sourcedir> <!--(1)-->
            <project-version>${project.version}</project-version> <!--(1)-->
            <imagesdir>./images</imagesdir> <!--(1)-->
            <icons>font</icons> <!--(1)-->

            <!-- HTML configuration -->
            <docinfo1>true</docinfo1> <!--(2)-->
            <idprefix/><!--(2)-->
            <idseparator>-</idseparator> <!--(2)-->
            <sectanchors>true</sectanchors> <!--(2)-->
            <toc>left</toc> <!--(2)-->
        </attributes>
    </configuration>
    <executions>
        <execution>
            <id>generate-pdf-doc</id> <!--(3)-->
            <phase>build</phase>
            <goals>
                <goal>process-asciidoc</goal>
            </goals>
            <configuration>
                <backend>pdf</backend>
                <attributes>
                    <docinfo1>false</docinfo1>
                    <idprefix/>
                    <idseparator>-</idseparator>
                    <pagenums/>
                    <toc/>
                    <sectanchors>false</sectanchors>
                </attributes>
            </configuration>
        </execution>
    </executions>
</plugin>

1. Shared configuration at plugin configuration.

2. Configuration for HTML5 output format at plugin configuration.

3. Configuration for PDF output format at its own execution configuration.

Some examples explained in detail

How to use the automatically created properties

Suposse you configure the asciidoctor-maven-plugin and the asciidoctor-lifecycle-maven-plugin as (I show you only the relevant configuration for this purpose):

<plugin>
    <groupId>com.coutemeier.maven.plugins</groupId>
    <artifactId>asciidoctor-lifecycle-maven-plugin</artifactId>
    <version>1.0-SNAPSHOT</version>
    <extensions>true</extensions>
    <configuration>
        <themesBaseDir>${project.build.directory}/asciidoctor-themes</themesBaseDir> <!--(1)-->
        <themes>
            <theme>com.coutemeier.maven.plugins:theme-example-1:zip:1.2.0</theme> <!--(2)-->
            <theme>com.coutemeier.maven.plugins:theme-example-2:zip:2.2.1</theme>
        </themes>
    </configuration>
</plugin>

<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>${asciidoctor.maven.plugin.version}</version>
    <dependencies>
        <dependency>
            <groupId>org.asciidoctor</groupId>
            <artifactId>asciidoctorj-pdf</artifactId>
            <version>${asciidoctorj.pdf.version}</version>
        </dependency>
    </dependencies>
    <executions>
        <execution>
            <id>generate-pdf-doc-custom-theme</id>
            <phase>build</phase>
            <goals>
                <goal>process-asciidoc</goal>
            </goals>
            <configuration>
                <backend>pdf</backend>
                <outputDirectory>${project.build.directory}/generated-docs-custom-theme</outputDirectory>
                <sourceHighlighter>coderay</sourceHighlighter>
                <doctype>book</doctype>
                <attributes>
                    <!--
                        The property "asciidoctor.theme.theme-example-1.path" is created at `theme` phase,
                        so it is not needed to define it in the pom.xml.
                    -->
                    <pdf-stylesdir>${asciidoctor.theme.theme-example-1.path}/pdf</pdf-stylesdir> <!--(3)-->
                    <pdf-style>custom</pdf-style>
                    <icons>font</icons>
                    <pagenums/>
                    <toc/>
                    <idprefix/>
                    <idseparator>-</idseparator>
                </attributes>
            </configuration>
        </execution>
    </executions>
</plugin>

1. The directory where themes will be unzipped (this is the default value).

2. You need the plugin whose coordinates are com.coutemeier.maven.plugins:theme-example-1:zip:1.2.0.

3. You configure the path of the theme using the property asciidoctor.theme.theme-example-1.path, created at theme phase.

After the theme phase execution you’ll get:

1. Two directories in the target/asciidoctor-themes:

   • theme-example-1

   • theme-example-2

2. Two properties are created in this phase, so you can use them in later phases.

   • asciidoctor.theme.theme-example-1.path = ${project.output.dir}/asciidoctor-themes/theme-example1

   • asciidoctor.theme.theme-example-2.path = ${project.output.dir}/asciidoctor-themes/theme-example2

In the build phase execution:

1. The property asciidoctor.theme.theme-example-1.path and asciidoctor.theme.theme-example-2.path are defined, so you can use them as a property to configure the path of the YAML file.

How to configure wagon for publishing

Let’s see an example to publish files to a webdav repository:

<plugin>
    <groupId>com.coutemeier.maven.plugins</groupId>
    <artifactId>asciidoctor-lifecycle-maven-plugin</artifactId>
    <version>1.0-SNAPSHOT</version>
    <extensions>true</extensions>
    <configuration>
        <serverId>webdav-snapshots</serverId> <!--(1)-->
        <publishToRepository>dav:http://localhost:8081/nexus/content/sites/test-site/</publishToRepository> <!--(2)-->
        <publishToDirectory>${project.artifactId}/${project.version}</publishToDirectory> <!--(3)-->
    </configuration>
    <!--
        You need the wagon-webdav-jackrabbit dependency
        if you want to publish to a webdav server
    -->
    <dependencies>
        <dependency>
            <groupId>org.apache.maven.wagon</groupId>
            <artifactId>wagon-webdav-jackrabbit</artifactId> <!--(4)-->
            <version>3.0.0</version>
        </dependency>
    </dependencies>
</plugin>

1. The server id corresponding to a server entry in settings.xml, with credentials to publishing the files to the server.

2. The url to which you want to publish the files.

3. The directory where you want to publish the files.

4. The dependency for wagon webdav support.

How can I build the plugin?

Conventional build

You can build the project with Maven [3.3.9,4.0) versions and Java 8.

mvn clean package

You can launch the integration tests:

mvn clean verify -Prun-it

Run tests in parallel

The profile with id=parallel allows running tests in parallel, so you can launch the tests as:

mvn clean test -Pparallel

or

mvn clean verify -Pparallel

Measure coverage

The profile with id=quality configure some additional actions, such as measuring coverage and submitting Java code coverage to the coveralls service.

mvn clean verify -Pparallel -Pquality

Warnings

Tests were redesigned using JUnit5 to run in CONCURRENT mode, so the reports are affected by the bug JUnit 5 in parallel execution mode confuses Surefire reports.

So please, ignore for the moment the wrong number of tests in surefire report, like:

[INFO] Tests run: 6, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.214 s - in com.coutemeier.maven.plugins.asciidoctor.lifecycle.util.ZipUtilTestCase
[INFO] Tests run: 0, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.266 s - in com.coutemeier.maven.plugins.asciidoctor.lifecycle.util.FileUtilTestCase
[INFO] Tests run: 0, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.21 s - in com.coutemeier.maven.plugins.asciidoctor.lifecycle.util.ArtifactUtilOtherTestCase
[INFO] Tests run: 4, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.418 s - in com.coutemeier.maven.plugins.asciidoctor.lifecycle.util.ArtifactUtilTestCase
[INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 1.925 s - in com.coutemeier.maven.plugins.asciidoctor.lifecycle.util.WagonUtilTestCase

References

• Asciidoctor home page

• asciidoctor-maven-plugin in Github