asciidoctor with multimodule maven project

Hi All!

I have a problem with asciidoc and I couldn't find any solution searching from the internet, so I try to ask for help here.

I have a multi module maven project. In the parent project I have the 'first part' of the asciidoc documentation and each module has its own chapter.

Then I have a 'distribution module'; this is the module where the asciidoc will get compiled and works this way:
1) An assembly copies all the asciidoc files and images from all the modules to a staging directory
2) the asciidoc maven plugin compiles the asciidoc files to create the manual (html output)

Inside the asciidoc document there is some 'include::' directive in the form of:

include::/my/project/parent/distribution/../module1/src/java/my/package/MyClass.java

The problem is that the code from MyClass.java does not get included, I see instead somethink like:

link:/my/project/parent/distribution/../module1/src/java/my/package/MyClass.java

in the generated code.

I guess it is related to the 'safe mode', but couldn't find any documentation on how to disable that on the maven plugin.

Any help is greatly appreciated!

Thanks in advance,
Massimiliano

welcome,
I don't think safe mode may be the cause because it is disabled by default, you can have a look at the code yourself:
https://github.com/asciidoctor/asciidoctor-maven-plugin/blob/master/src/main/java/org/asciidoctor/maven/AsciidoctorMojo.java#L143

I think the issue may be related to the path system when using multimodules, keep in mind that each module uses a different baseDir. You can try to set the base path used to search for resources with baseDir, but it should be set in each module accordingly to its relative path to the parent, e.g. "../" to set the base at the parent from a lvl-1-depth module. Have you tried it?

Also, just for the sake of testing, have you tried to set absolute paths?

Thank you abelsromero!

The problem is that the path showed inside the html exists!
I mean, in the html I have something like :

include::/my/project/parent/distribution/../module1/src/java/my/package/MyClass.java

if I do:

ls /my/project/parent/distribution/../module1/src/java/my/package/MyClass.java

the file exists!

And, as you can see, the path is already absolute.

abelsromero wrote

keep in mind that each module uses a different baseDir

All the paths I use are absolute (I use maven to substitute a variable inside each asciidoc file while copying it in the staging directory)

Thanks you!
Massimiliano

I have build a test myself to try to reproduce it, basically a multi-module with a parent a 2 child projects (A and B).
Then I include a Java file from A to B (that is the 'include' is in an adoc file in B), I don't have any staging here.

Overall absolute paths work fine for me, even when I include some parent browsing (with \..\), on Windows thought (I used cygwin, but the plugin gets Windows' paths anyway :/ ).
And a thing that puzzles me is that ocurrence of 'link' you commented, I haven't been able to get that behauviour. The closer I got was removing the ending brackets [], which causes a simple 'include' to appear.
When a file is not found I get a warning message in the console and this in the HTML:
Unresolved directive in SomeGuide.asciidoc - include::I:\workspace\asciidoctor\asciidoctor-maven-test\sub-project-A\src\main\java\example\FAKE_HelloJava.java[]

Seeing that this approach it not helping I'd like to review your case to make sure I understand everything, is that ok for you?
· The maven plugin is only configured in the 'distribution' module, is that right?
· Although all files are found in several modules, they're rendered from a single folder where they're previously copied. right?
· Also, can you elaborte on the 'staging' process? Is just a copy process or somthing else is done? You mentioned some replacements.


If the answer to the first two is true and staging only copies and replaces include paths, I would approach the configuration in a diferent way:
1. First, I'd set the baseDir in the distribution module to point to the parent folder with something like this:

        <baseDir>${project.parent.basedir}</baseDir>

2. With that in place you should be able to include files from any project with a relative address, for instance, to include a Java and AsciiDoc file you could do:

    include::moduleA/path_to_adoc/file_to_include.adoc[]
    include::moduleB/src/main/java/JavaToInclude.java[]

To ease the configuration and avoid errors you could define some vars for conventional paths:

    include::module/{asciidoc-sources}/file_to_include.adoc[]
    include::module/{java-main-sources}/JavaToInclude.java[]

Of course, if your case includes more details and is more complex (which I suspect) this won't help.

Hi Abelsromero!

Thanks for your help.

I created a sample project that you can download from https://db.tt/IVF159Wo that replicates the problem.

Just run

mvn install

in the root directory, and then give a look at the generated html files in

distributions/target/generated-docs

And you will see the problem.

Regards,
Massimiliano

Good news, I could reproduce the issue and you'll laugh at the solution.
After some tests, experiments and a couple of hours I saw you're using the plugin version 1.5.0, with the latests 1.5.2 it works :D

Other than that, the test has 2 small typos in `module2.asciidoc` and in the sourceHighlighter tag, check the capital H. And the # characters at the beginning of each file cause an error message to be shown the parsing the last one...weird.

BTW, the example is really nice and solves 2 important problems quite nicely:
· Documenting a multi-module API on each project while keeping a common part in the parent.
· Assembling the documents in a single folder to create a distributable package. For instance, to move the docs into an Apache server.
Why don't you upload it to GitHub so we can link it?

Hi Abelsromero,

I saw you're using the plugin version 1.5.0, with the latests 1.5.2 it works :D

shame on me!!! Sorry for that!!

Other than that, the test has 2 small typos in `module2.asciidoc` and in the sourceHighlighter tag, check the capital H. And the # characters at the beginning of each file cause an error message to be shown the parsing the last one...weird.

Yep you are right.

BTW, the example is really nice and solves 2 important problems quite nicely:
· Documenting a multi-module API on each project while keeping a common part in the parent.
· Assembling the documents in a single folder to create a distributable package. For instance, to move the docs into an Apache server.
Why don't you upload it to GitHub so we can link it?

Done.
You can find it on https://github.com/ziccardi/asciidoc

Thanks a lot for your help!

Regards,
Massimiliano

Regarding adding examples to 'asciidoctor-maven-examples', I'm usually confused about what should be the strategy. Specially in cases like one, which are very interesting but they involve more work on the maven side than in asciidoctor's.

I'm thinking we could extend the introduction to elaborate a bit more and make things easier for anyone who wants to contribute an example and for all of us to decided whether it should be included.
What do you think of this (in bold the addition):

This repository contains a collection of sample projects that demonstrate numerous ways to use the Asciidoctor Maven plugin as well as different scenarios for maven integration.