Documentation fails to build when project path contains accented characters

[oliviercailloux]

Jetty version
Both 9.4.x and 10.0.x.

Java version
openjdk version "11.0.8" 2020-07-14

OS type/version
Debian buster

Description
The docbkx plugin, required to build the documentation, (sometimes?) fails to run when the project path contains an accented character (Développement, for example). Strangely enough, the problem does not arise when the path contains spaces and no accented character.

To reproduce, move into a folder whose full path contains an accented character, then:

git clone git@github.com:eclipse/jetty.project.git
cd jetty.project
cd jetty-documentation
mvn package

=> you will obtain: [ERROR] Failed to execute goal com.agilejava.docbkx:docbkx-maven-plugin:2.0.17:generate-html (html) on project jetty-documentation: Failed to transform index.xml.: Failure reading [fullpath]/jetty.project/jetty-documentation/target/generated-docs/index.xml: no protocol: [fullpath]/jetty.project/jetty-documentation/target/generated-docs/index.xml -> [Help 1]

I just reported this bug to the docbkx-tools project for documentation purposes, but, considering that the relevant plugin is now unmaintained, it is highly unlikely that it will get fixed.

I do not claim that this bug should get high priority, as it has a simple workaround, and as fixing it might be very hard (requiring to delve into a plugin which the jetty team has nothing to do about, I suppose). Therefore, I suggest to simply add a comment in the pom of the jetty-documentation module, to warn users so that they do not waste time (as I did) before realizing where the problem lies. Or, hopefully, this bug report will be enough, once indexed by the main web search engines.

To summarize, this bug report only intends to document this behavior so as to help others, not really ask for a patch. (Of course if you know of an easy patch, that’s even better.)

[lachlan-roberts]

Looks like from Jetty-10 onwards we are using only asciidoctor plugin to generate the documentation instead of using docbkx. I have tested on 10.0.x and I could not reproduce the same problem.

[oliviercailloux]

You are right. My bad. The problem I encountered with 10.0.x differs (doc requires other modules, and I can’t mvn test the whole project because some tests fail). So this bug report concerns only the 9.4.x branch.

[lachlan-roberts]

@oliviercailloux If you want to build the documentation in 10.0.x you could run mvn clean install -DskipTests for the whole project. Then go specifically to the jetty-documentation directory and run mvn clean install. That should allow you to build the documentation without running any tests.

@WalkerWatch is there any reason we need docbkx for 9.4.x and we can't do the same thing we do in jetty-10?

[janbartel]

@WalkerWatch can you evaluate this issue, and close if it has been addressed.

[joakime]

If you cloned your jetty project into a directory name with escaped characters it can also mess up the asciidoc and docbook plugins.

Example:

git clone git@github.com:eclipse/jetty.project.git "jetty%2Fproject"
cd "jetty%2Fproject"
cd jetty-documentation
mvn package

Many CI build tools (jenkins, travis, github CI, etc) will clone into the name of the branch, so branches like joakime/jetty-9.4.x/issue-5299 would result in a clone to a directory joakime%2fjetty-9.4.x%2fissue-5299 which can break a surprising number of libraries. (esp around documentation and osgi)

[WalkerWatch]

Docbook has been removed in 9.4.x in #5636