About Asciidoctor Maven integration: A custom lifecycle

classic Classic list List threaded Threaded
13 messages Options
Reply | Threaded
Open this post in threaded view
|

About Asciidoctor Maven integration: A custom lifecycle

rrialq
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?
Reply | Threaded
Open this post in threaded view
|

Re: About Asciidoctor Maven integration: A custom lifecycle

Alexander Schwartz
I've come across similar situations in the past. I usually solved this by adding profiles to the maven project. Selecting one or several profiles allowed me to build the application, the documentation or both.

The maven lifecycle already supports several phases like 'initialize', 'generate-sources', 'process-sources', etc. and I wonder how your phases could map to existing phases.

The asciidoctor-maven-plugin has its own GitHub repository, maybe opening an issue there would be the place to discuss this: https://github.com/asciidoctor/asciidoctor-maven-plugin
Alexander Schwartz (alexander.schwartz@gmx.net)
https://www.ahus1.de
Reply | Threaded
Open this post in threaded view
|

Re: About Asciidoctor Maven integration: A custom lifecycle

rrialq
In my current projects I use a profile to download a theme (with dependency:get and unpack it) , build the module with asciidoctor), zip the results and send the files to a Nexus site repository, but this is too much complicated if you want to reply this across multiple projects. This profile is in a parent pom, but this is not as effective as we need, because of using the default lifecycle.

I have developed a custom lifecycle that meets my needs, but I don't know if meet other people needs.
I will publish the code in github next days, when I finish the tests.

The new lifecycle contains its own phases, so it allows to build only the documentation, because when you want to build it you use mvn build, and this lifecycle does not overlap with the default, so I think it is a better approach than using the standard lifecycle.

Think in the site lifecycle, it also does not overlap with the standard lifecycle, and it exists to solve the problem of the site documentation.
Reply | Threaded
Open this post in threaded view
|

Re: About Asciidoctor Maven integration: A custom lifecycle

abelsromero
I have to say I am a bit reluctant (but not 100% closed) to such approach for practical reasons, but it makes totally sense. I too have relied in profiles and try to adhere to mavens life-cycle, and is not always perfect and it feels "shoehorned". But that's a consequence of maven's core design philosophy.

A custom lifecycle requires much though to accommodate future scenarios and implies several decisions that can limit future options and imposes certain patterns. For example, should we publish in zip or jar? should we create a sources artifact also? should package resources separatedly with a maven classifier?
See the discussion: https://github.com/asciidoctor/asciidoctor-maven-plugin/issues/321 to get some ideas.

The thing is when you go deep into this, you end-up modeling a whole building, reuse & distribution solutions. And if that's the case, and you just publish HTML, I'd highly recommend checking out Antora.

Said that, if we can add this as an extra options without changing current behavior we can explore it. But I'd recommend aligning with the default's maven lifecyle as much as possible. That way it's easier to understand for users and we can inject more steps in the build process without issues. One case for example where it makes sense is when integrating plugins that create temporal files, a "prepare-*" phase would make sense to move files to a staging area.
Note this requires to rebuild the plugin into several sub-plugins for each phase.
Reply | Threaded
Open this post in threaded view
|

Re: About Asciidoctor Maven integration: A custom lifecycle

rrialq
The custom lifecycle I have developed define several phases, but only one of them is associated to a Mojo.
Why?
Because in this state is only a proof of concept, to take a look the pros and cons, and for resolving my particular needs.

So the decission about if you deploy a zip file to a repository, upload the html files generated, the pdf or if you want to attach the result of zip the generated files is customizable. How? In the same way as with another plugins:
with the executions.

The lifecycle will simplify the settings, and the lifecycle of the main artifacts will be independent from the build of the documentation.

For example, before that lifecycle, for downloading a pdf theme for Asciidoctor I wrote a configuration similar to:

   
    <plugin>
        <artifactId>maven-dependency-plugin</artifactId>
        <version>${plugin-version.maven-dependency}</version>
        <executions>
            <execution>
               
                <id>asciidoctor-theme-unpack</id>
                <phase>prepare-package</phase>
                <goals>
                    <goal>unpack</goal>
                </goals>
                <configuration>
                    <artifact>com.coutemeier.mydoctor.theme:mydoctor-pdf-theme:1.0-SNAPSHOT</artifact>
                    <outputDirectory>${project.build.directory}/mydoctor-themes</outputDirectory>
                    <overWriteIfNewer>true</overWriteIfNewer>
                    <overWriteSnapshots>true</overWriteSnapshots>
                </configuration>
            </execution>
        </executions>
    </plugin>

   
    <plugin>
         <groupId>org.codehaus.mojo</groupId>
         <artifactId>wagon-maven-plugin</artifactId>
         <version>${version.mohojaus-wagon}</version>
         <executions>
             <execution>
                 <id>upload-to-nexus</id>
                 <phase>deploy</phase>
                 <goals>
                     <goal>upload</goal>
                 </goals>
                 <configuration>
                     <includes>**/*</includes>
                 </configuration>
             </execution>
         </executions>
    </plugin>

Take care of prepare-package, or replace it with another phase of the default lifecycle.
When you execute a mvn package, in a multimodule, and you want build everything except documentation, your only help is the use of profiles.

If you are working on the asciidoctor documentation, and you want to build it (but not the rest) you have a problem: you need to configure your pom with multiple profiles and properties to get it. This is not practical, neither easy to mantain.

With the new lifecycle you can configure as:

   
    <plugin>
        <groupId>com.coutemeier.maven.plugins</groupId>
        <artifactId>mydoctor-maven-plugin</artifactId>
        <version>1.0-SNAPSHOT</version>
        <extensions>true</extensions>
        <configuration>
            <themes>
                <theme>com.coutemeier.mydoctor.theme:mydoctor-pdf-theme:1.0-SNAPSHOT</theme>
            </themes>
            </themesBaseDir>${project.build.directory}/mydoctor-themes</themesBaseDir>
        </configuration>
    </plugin>

    <plugin>
         <groupId>org.codehaus.mojo</groupId>
         <artifactId>wagon-maven-plugin</artifactId>
         <version>${version.mohojaus-wagon}</version>
         <executions>
             <execution>
                 <id>upload-to-nexus</id>
                 <phase>upload</phase>
                 <goals>
                     <goal>upload</goal>
                 </goals>
                 <configuration>
                     <includes>**/*</includes>
                 </configuration>
             </execution>
         </executions>
    </plugin>

So when I execute mvn package it will package the project, but will not process the asciidoctor documentation.
And when I execute mvn build it will process the asciidoctor documentation, but will not compile or package the project.
In the same way as the site lifecycle.

If I want doing all the work, mvn upload will do all the work for asciidoctor documentation, including the upload to the Nexus repository site.

Of course, you can configure other plugins to upload to another repository, with another protocol (http, ssh, webdav...), and binding to the phase upload to to this job.

And I want to include another features:
* Packing the generated files as a new goal, may be using the zip goal of asciidoctor-maven-plugin: write less configuration.
* Define what is an mydoctor theme, the structure, the contents... may be in the future, not now. For the moment a theme is only a zip file with some contents that you will use as you want.
* Write a mojo to upload the generated files to a server...
Reply | Threaded
Open this post in threaded view
|

Re: About Asciidoctor Maven integration: A custom lifecycle

rrialq
In reply to this post by rrialq
I've just created the mydoctor-maven-plugin, for hosting the code project.

In https://github.com/mydoctor-maven-plugin/mydoctor-maven-plugin you find the code of this new plugin and the documentation for using it in your projects.

It is in an early stage, but you can use it, fork it, make pull requests and suggest new funcionalities or send issues.
Reply | Threaded
Open this post in threaded view
|

Re: About Asciidoctor Maven integration: A custom lifecycle

mojavelinux
Administrator
I was going to suggest a new plugin that offers this more advanced functionality, so I'm glad to see you went ahead and created it. Like Abel was saying, we're not closed to it. It's just that we need to retain a basic plugin for the average use case. But in no way does that rule out having an advanced lifecycle plugin.

The only thing I'd suggest is to try to be a little less cute with the name. "mydoctor" really doesn't communicate what it is. Perhaps asciidoctor-lifecycle-maven-plugin, or something more descriptive would be better. Just hacking up the name of a project makes it hard to gain traction because it looks unrelated. And it also dilutes the brand of the project name. (For example, you don't say "myyota" when you name a Toyota community site).

Best,

-Dan

On Tue, Aug 13, 2019 at 9:41 AM rrialq [via Asciidoctor :: Discussion] <[hidden email]> wrote:
I've just created the mydoctor-maven-plugin, for hosting the code project.

In https://github.com/mydoctor-maven-plugin/mydoctor-maven-plugin you find the code of this new plugin and the documentation for using it in your projects.

It is in an early stage, but you can use it, fork it, make pull requests and suggest new funcionalities or send issues.


If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/About-Asciidoctor-Maven-integration-A-custom-lifecycle-tp7063p7076.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML


--
Dan Allen | @mojavelinux | https://twitter.com/mojavelinux
Reply | Threaded
Open this post in threaded view
|

Re: About Asciidoctor Maven integration: A custom lifecycle

abelsromero
I am glad you went ahead, I have to say the quality of the code far surpasses what I consider "a first approach" and seeing the examples it is much simpler than what I though.
I must have a look asap and start opening issues/PR to discuss things.
Reply | Threaded
Open this post in threaded view
|

Re: About Asciidoctor Maven integration: A custom lifecycle

rrialq
In reply to this post by mojavelinux
Hi, mojave.

I chose that name because I didn't know if it would be legal to use asciidoctor as part of the name.
My first choice was asciidoctor-lifecycle-maven-plugin.
I finally decided to change it so as not to disturb the community asciidoctor.

I will rename this to asciidoctor-lifecycle-maven-plugin. Please, wait till I finished before opening issues.

About the functionality.
* I have started to write this plugin to simplify a big parent pom I wrote to manage my needs. I think many of us have the same problems about this and a similar way to solve them.
* A lifecycle is only an xml file, where you define the phase names in sequential order, and if any phase is binded to a mojo.
* The plugin contains a new mojo for downloading themes.

Imagine we merge my project with asciidoctor-maven-plugin (I think it has sense in the future, to minimize configuration; for now I think is a better idea to separate them to allow a fasterevolution of the asciidoctor-maven-plugin).
* What should do somebody that only want the basic functionality? Using the same configuration as nowday, binding the mojos to phases in the default lifecycle (no change from current documentation).
* What should do somebody that want the functionality of the lifecycle? Using the documentation in this plugin.

So both of functionalities can be combined in the same plugin and using one or another as your own needs.




mojavelinux wrote
I was going to suggest a new plugin that offers this more advanced
functionality, so I'm glad to see you went ahead and created it. Like Abel
was saying, we're not closed to it. It's just that we need to retain a
basic plugin for the average use case. But in no way does that rule out
having an advanced lifecycle plugin.

The only thing I'd suggest is to try to be a little less cute with the
name. "mydoctor" really doesn't communicate what it is. Perhaps
asciidoctor-lifecycle-maven-plugin, or something more descriptive would be
better. Just hacking up the name of a project makes it hard to gain
traction because it looks unrelated. And it also dilutes the brand of the
project name. (For example, you don't say "myyota" when you name a Toyota
community site).

Best,

-Dan

On Tue, Aug 13, 2019 at 9:41 AM rrialq [via Asciidoctor :: Discussion] <
[hidden email]> wrote:

> I've just created the mydoctor-maven-plugin, for hosting the code project.
>
> In https://github.com/mydoctor-maven-plugin/mydoctor-maven-plugin you
> find the code of this new plugin and the documentation for using it in your
> projects.
>
> It is in an early stage, but you can use it, fork it, make pull requests
> and suggest new funcionalities or send issues.
>
> ------------------------------
> If you reply to this email, your message will be added to the discussion
> below:
>
> http://discuss.asciidoctor.org/About-Asciidoctor-Maven-integration-A-custom-lifecycle-tp7063p7076.html
> To start a new topic under Asciidoctor :: Discussion, email
> [hidden email]
> To unsubscribe from Asciidoctor :: Discussion, click here
> <http://discuss.asciidoctor.org/template/NamlServlet.jtp?macro=unsubscribe_by_code&node=1&code=ZGFuLmouYWxsZW5AZ21haWwuY29tfDF8MTY5MzI5MDU4>
> .
> NAML
> <http://discuss.asciidoctor.org/template/NamlServlet.jtp?macro=macro_viewer&id=instant_html%21nabble%3Aemail.naml&base=nabble.naml.namespaces.BasicNamespace-nabble.view.web.template.NabbleNamespace-nabble.view.web.template.NodeNamespace&breadcrumbs=notify_subscribers%21nabble%3Aemail.naml-instant_emails%21nabble%3Aemail.naml-send_instant_email%21nabble%3Aemail.naml>
>


--
Dan Allen | @mojavelinux | https://twitter.com/mojavelinux
Reply | Threaded
Open this post in threaded view
|

Re: About Asciidoctor Maven integration: A custom lifecycle

rrialq
In reply to this post by abelsromero
Thank you.
The code needs unit tests and quality analysis. It is essential from my point of view.
I know the code works right because I use it with the integration tests, and with some of my projects.
But the phases need dicussion. Which phases to do what? In what order?

For example, the post-build phase gives the false impression that it will be executed after the build phase.
So I will rename it to pre-upload. Indicates more precisely when it will run

I will rename this to asciidoctor-lifecycle-maven-plugin. Please, wait till I finished before opening issues.

I will rename the project to asciidoctor-lifecycle-maven-plugin, as mojave suggest.
Please, be patient till I've finish the rename before opening issues, because I don't know if it is possible to rename the name of the organization in GitHub.

abelsromero wrote
I am glad you went ahead, I have to say the quality of the code far surpasses what I consider "a first approach" and seeing the examples it is much simpler than what I though.
I must have a look asap and start opening issues/PR to discuss things.
Reply | Threaded
Open this post in threaded view
|

Re: About Asciidoctor Maven integration: A custom lifecycle

mojavelinux
Administrator
In reply to this post by rrialq
> I chose that name because I didn't know if it would be legal to use asciidoctor as part of the name.

Just ask. We're all about empowering the community, so if you ask, we'll likely welcome you to use it ;)

> My first choice was asciidoctor-lifecycle-maven-plugin.

+1

Seems like a good fit to me.

Cheers,

-Dan

--
Dan Allen | @mojavelinux | https://twitter.com/mojavelinux
Reply | Threaded
Open this post in threaded view
|

Re: About Asciidoctor Maven integration: A custom lifecycle

rrialq
I have finished the rename of the project, organization in Github, asciidoctor-lifecycle-maven-plugin.

The code has refactorized to reflect the new plugin name.
So it is ready to start the hard job.
Please, feel free to create issues to discuss about the lifecycle, mojos or other related questions.

Any help will be welcome.
Reply | Threaded
Open this post in threaded view
|

Re: About Asciidoctor Maven integration: A custom lifecycle

rrialq
I've just created the asciidoctor-lifecycle-maven-examples, to show how to use the new lifecycle with examples.
I will try to reply the same examples as in asciidoctor-maven-examples.

The first example created is a basic html document.