Posted by rrialq on Aug 10, 2019; 12:52pm
URL: https://discuss.asciidoctor.org/About-Asciidoctor-Maven-integration-A-custom-lifecycle-tp7063.html

Hello.

I am working with the asciidoctor-maven-plugin and I find with the default Maven lifecycle is very difficult (maybe impossible) separate the build of documentation from the build of the artifacts.

In Maven exists the site lifecycle to allow the build of the documentation of the site without building the main artifacts of the project, with its custom upload (site-deploy).

But there is nothing similar for Asciidoctor (and no, I am not talking about asciidoctor-maven-plugin site integration, I want pure Asciidoctor builds from Maven).

Which reasons I have to separate the build of the documentation from the build of the artifacts?
1 If we define some modules with asciidoctor documentation, and others (jar packaging, war packaging...), we can not build only the documentation, because the phases of the standard lifecycle will perform its normal functionality (generate-sources, compile, package, ...).
2. If we try to use an advanced configuration with the help of the wagon plugin to upload the generated contents, we can not separate in a simply way the upload of the artifacts and the upload of the asciidoctor documentation.
3. In Continuous Integration we can divide the builds in full builds (artifacts, all tests and documentations) and simple builds (artifacts and unit tests) for speed. With the default lifecycle this is not possible.

So I start to write a custom lifecycle for building asciidoctor modules, with the hope to simplify many of the requirements of buliding and deploying documentation, following this lifecycle:

* theme-download: for downloading a theme from a repository and unpack it to a folder. A theme is a zip file, with the content you decide. This is a specific Maven mojo, so you only need to configure the artifact which contains the theme.
* generate-documentation: after theme downloaded and unpacked, this gives an opportunity for overwrite some of the files of the theme, with a custom version of it, or creating new files.
* pre-build: to do things before the build.
* build: build the asciidoctor documentation.
* post-build: for doing things after the build (may be create a zip file with the content of the generated files).
* upload: for upload the generated files to a server.
* notify: an oportunity of notifying availability of documentation.

So with the help of this new Maven lifecycle you can configure and separate the execution of goals attached to asciidoctor build instead of phases of the default lifecycle.

Do you think this is something interesting enough to complement the asciidoctor-maven-plugin?