How to use the asciidoctor-maven-plugin to compile a separate jar package for asciidoc

Hi everyone,

Frist, I am developing a maven project, and now I need compile this project with a help doc module. In other words,

how to compile two jars with asciidoctor plugin when run "mvn clean install":
1. one is for the base function
2. other one is for showing the help document

what I need do, or how to configure the pom.xml?

Need maven-jar-plugin, asciidoctor-maven-plugin, maven-resources-plugin?

Thanks!

Hi,

I understand you need to generate 2 different jars with totally separated content all at once. If so, that's one case in which maven does not shine, but it's possible.

EDITED: I found a much better alternative solution, to I am removing my previous post. Apologies.

First, you need to set up a new jar with a custom classifier, check this: https://maven.apache.org/plugins/maven-jar-plugin/examples/attached-jar.html. Similarly to how you can generate an artifact-sources.jar, artifact-javadoc.jar, etc. you can create a custom "artifact-asciidocs.jar".
The tricky part is that you need to align the </outputDirectory> from asciidoctor-maven-plugin with <classesDirectory> in maven-jar-plugin. I'd recommend to use a property, for instance I wrote an example pointing both to `${build.outputDirectory}/my-generated-docs`.

One consideration to have in mind is adding the output format to the classifier. Just in case you want to generate a jar with html and another with pdf for example, and be able to diferentiate them.

Hi， abelsromero

In fact, I have implemented two jars, but I do not think my way is right. now I give my steps and the wrong parts.

S1: I define the maven project like this:


S2: and My pom configuration as below:
<build>
                <resources>
                        <resource>
                                <directory>src/main/java</directory>
                                <excludes>
                                        <exclude>**/*.java</exclude>
                                </excludes>
                        </resource>
                        <resource>
                                <directory>${basedir}/src/main/resources</directory>
                        </resource>
                        <resource>
                                <directory>${project.build.directory}/docs/</directory>
                                <excludes>
                                        <exclude>**/*.adoc</exclude>
                                        <exclude>**/*.pdf</exclude>
                                </excludes>
                                <includes>
                                        <include>**/images/*</include>
                                        <include>**/en/index.html</include>
                                        <include>**/en/*.css</include>
                                </includes>
                        </resource>
                </resources>
                <plugins>
                        <plugin>
                                <groupId>org.apache.felix</groupId>
                                <artifactId>maven-bundle-plugin</artifactId>
                                <extensions>true</extensions>
                                <configuration>
                                        <instructions>
                                                <Bundle-SymbolicName>${project.groupId}.${project.artifactId}</Bundle-SymbolicName>
                                                <Bundle-Activator>XXX.internal.Activator</Bundle-Activator>
                                                <SCM-Version>v${scmVersion}</SCM-Version>
                                                <Contains-Manual>Y</Contains-Manual>
                                                <Export-Package>
                                                </Export-Package>
                                                <Import-Package>       
                                                </Import-Package>
                                                <Include-Resource>
                                                        ...
                                                </Include-Resource>
                                        </instructions>
                                </configuration>
                        </plugin>
                        <plugin>
                                <groupId>org.asciidoctor</groupId>
                                <artifactId>asciidoctor-maven-plugin</artifactId>
                                <executions>
                                        <execution>
                                                <id>output-html</id>
                                                <phase>generate-resources</phase>
                                                <goals>
                                                        <goal>process-asciidoc</goal>
                                                </goals>
                                                <configuration>
                                                        <sourceHighlighter>coderay</sourceHighlighter>
                                                        <backend>html</backend>
                                                        <attributes>
                                                                <project-version>${project.version}</project-version>
                                                                <linkcss>true</linkcss>
                                                                <sectnums>true</sectnums>
                                                                <toc>left</toc>
                                                                <toclevels>4</toclevels>
                                                                <icons>font</icons>
                                                        </attributes>
                                                </configuration>
                                        </execution>
                                </executions>
                                <configuration>
                                        <preserveDirectories>true</preserveDirectories>
                                        <relativeBaseDir>true</relativeBaseDir>
                                        <sourceDirectory>
                                                docs/help</sourceDirectory>
                                        <outputDirectory>${project.build.directory}/docs/help</outputDirectory>
                                        <headerFooter>true</headerFooter>
                                        <imagesDir>images</imagesDir>
                                </configuration>
                        </plugin>
                        <plugin>
                                <artifactId>maven-jar-plugin</artifactId>
                                <executions>
                                        <execution>
                                                <id>HELP</id>
                                                <phase>package</phase>
                                                <goals>
                                                        <goal>jar</goal>
                                                </goals>
                                                <configuration>
                                                        <classifier>HELP</classifier>
                                                        <archive>
                                                                <manifest>
                                                                        <addDefaultImplementationEntries>false</addDefaultImplementationEntries>
                                                                        <addDefaultSpecificationEntries>false</addDefaultSpecificationEntries>
                                                                </manifest>
                                                                <manifestEntries>
                                                                        <Bundle-SymbolicName>${project.groupId}.${project.artifactId}.HELP</Bundle-SymbolicName>
                                                                        <SCM-Version>v${scmVersion}</SCM-Version>
                                                                        <Bundle-ManifestVersion>2</Bundle-ManifestVersion>
                                                                        <Web-ContextPath>/${project.groupId}.${project.artifactId}</Web-ContextPath>
                                                                </manifestEntries>
                                                        </archive>
                                                        <includes>
                                                                <include>**/**/help/**/images/*.*</include>
                                                                <include>**/**/help/en/index.html</include>
                                                                <include>**/**/help/en/*.css</include>
                                                        </includes>
                                                </configuration>
                                        </execution>
                                </executions>
                        </plugin>
                </plugins>
        </build>

and I run "mvn clean install", generate two jars:



Thanks !!!

The problem is that you are adding the maven oputput to as a <resources>.
With that you'll be adding all files located there in any component that follows maven-jar-plugin conventions.
You can do that, but then you have to exclude what you don't want in the docs and code jar.

The idea I had in mind was creation 2 different and TOTALLY SEPARATED folder structures:
* 1 for the jar
* 1 for the docs
That way you don't need to mess with excludes/includes, just point to the folder you want to use for each jar.

To do that what I did was:
1. Create a property in the pom to store the path of generated docs:
<output.path>${project.build.outputDirectory}/my-generated-docs</output.path>

2. Set that as output in the asciidoctor-maven-plugin configuration.
 <outputDirectory>${output}/path</outputDirectory>

3. Set the generates docs path as `classesDirectory` in the "HELP" configuration of the maven-jar-plugin. This property tells the plugin to copy everything inside the folder. Provided you don't overlap code/resources with docs,
 it's fine.
<classesDirectory>${output.path}</classesDirectory>

No need to exclude or include anything.

Still, I am not sure that will interact with the OSGi`maven-bundle-plugin`, but I don't see why it shouldn't work.
If you have problems, just create an example on GitHub/GitLab and we can work on it.

I have not found this  `maven-bundle-plugin` to support the <excludes> , just use maven-resource-plugin to sove it for time bing.

I will post a example or problem on github if I haven't solved the problem yet

Thank you for your reply, best wishes.