in Maven RHQ API Docs ~ read.
Build API Docs for the RHQ Project

Build API Docs for the RHQ Project

Granted, this blog post will only likely interest the following audience:

  • Red Hat associates.

  • Folks using the upstream RHQ project.

  • Folks interested in techniques for generating API docs using Maven.

There are two parts to this post:

  • The Original Process

    • This covers the steps I took to build RHQ in a hope that others will benefit from it.

    • Some interesting take-aways about what happens when you forget to provide pre-requisite content in a procedure.

  • The Actual Process

    • When we get to this point, I’ll put the actual procedure you need to follow to produce the API docs.

The Original Process

The original process was:

  1. $ yum install maven

  2. $ git clone https://github.com/rhq-project/rhq.git jon

  3. $ cd jon

  4. $ cd modules/enterprise/server/jar

  5. $ mvn -Ddocgen install (or compile)

But after five attempts lasting over three days, I now know this is misleading to say the least.

First Attempt: No Success

I ran the steps in the process, and sat back with a cuppa tea…​

Note the build time…​

Downloaded: http://repo.maven.apache.org/maven2/org/mockito/mockito-all/1.9.0/mockito-all-1.9.0.jar (1461 KB at 76.0 KB/sec)
Downloaded: http://repo.maven.apache.org/maven2/org/testng/testng/6.5.2/testng-6.5.2.jar (701 KB at 36.4 KB/sec)
[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 15:13 min
[INFO] Finished at: 2015-02-16T10:00:51+10:00
[INFO] Final Memory: 19M/242M
[INFO] ------------------------------------------------------------------------
[ERROR] Failed to execute goal on project rhq-enterprise-server: Could not resolve dependencies for project org.rhq:rhq-enterprise-server:ejb:4.14.0-SNAPSHOT: The following artifacts could not be resolved: org.rhq:rhq-enterprise-comm:jar:4.14.0-SNAPSHOT, org.rhq:rhq-enterprise-server-xml-schemas:jar:4.14.0-SNAPSHOT, org.rhq:rhq-core-domain:jar:4.14.0-SNAPSHOT, org.rhq:rhq-cassandra-schema:jar:4.14.0-SNAPSHOT, org.rhq:rhq-core-plugin-api:jar:4.14.0-SNAPSHOT, org.rhq:rhq-core-client-api:jar:4.14.0-SNAPSHOT, org.rhq:rhq-core-dbutils:jar:4.14.0-SNAPSHOT, org.rhq:safe-invoker:jar:4.14.0-SNAPSHOT, org.rhq:rhq-common-drift:jar:4.14.0-SNAPSHOT, org.rhq:rhq-server-metrics:jar:4.14.0-SNAPSHOT, org.rhq:rhq-cassandra-util:jar:4.14.0-SNAPSHOT, org.rhq:rhq-jboss-as-dmr-client:jar:4.14.0-SNAPSHOT, org.rhq:test-utils:jar:4.14.0-SNAPSHOT, org.rhq.helpers:rest-docs-generator:jar:4.14.0-SNAPSHOT, org.rhq:rhq-core-domain:jar:tests:4.14.0-SNAPSHOT: Could not find artifact org.rhq:rhq-enterprise-comm:jar:4.14.0-SNAPSHOT in sonatype-snapshots (https://oss.sonatype.org/content/repositories/snapshots/) -> [Help 1]
[ERROR]
[ERROR] To see the full stack trace of the errors, re-run Maven with the -e switch.
[ERROR] Re-run Maven using the -X switch to enable full debug logging.
[ERROR]
[ERROR] For more information about the errors and possible solutions, please read the following articles:
[ERROR] [Help 1] http://cwiki.apache.org/confluence/display/MAVEN/DependencyResolutionException

I can’t really complain about this though: the first time you build a Maven project, you can expect it to take a long time as it downloads the required dependencies.

The error at this stage suggests I need to build the required dependencies myself before the DocGen tool will work.

No worries!

Second Attempt: Build Deps?

Luckily the folks in the RHQ project have made dependency building as simple as possible.

In the root of the project there is this script:

$ ./build-deps.sh

Run this script, and it orchestrates the dependency build process for the project. This type of automation is great for folks wanting to easily build the project. Great work RHQ team!

The script and the resulting process completed successfully, and I thought I was ready to run DocGen.

Not. So. Fast.

It turns out that this script builds the Cassandra dependencies. These are unrelated to the DocGen process, but there was nothing in the repo to tell me that.

Third Attempt: Run DogGen at Project Root?

I ran $ mvn -Ddocgen install and got this result.

[INFO] ------------------------------------------------------------------------
[INFO] Building RHQ Enterprise Server JAR 4.14.0-SNAPSHOT
[INFO] ------------------------------------------------------------------------
[WARNING] The POM for org.rhq:rhq-enterprise-comm:jar:4.14.0-SNAPSHOT is missing, no dependency information available
[WARNING] The POM for org.rhq:rhq-enterprise-server-xml-schemas:jar:4.14.0-SNAPSHOT is missing, no dependency information available
[WARNING] The POM for org.rhq:rhq-core-domain:jar:4.14.0-SNAPSHOT is missing, no dependency information available
[WARNING] The POM for org.rhq:rhq-cassandra-schema:jar:4.14.0-SNAPSHOT is missing, no dependency information available
[WARNING] The POM for org.rhq:rhq-core-plugin-api:jar:4.14.0-SNAPSHOT is missing, no dependency information available
[WARNING] The POM for org.rhq:rhq-core-client-api:jar:4.14.0-SNAPSHOT is missing, no dependency information available
[WARNING] The POM for org.rhq:rhq-core-dbutils:jar:4.14.0-SNAPSHOT is missing, no dependency information available
[WARNING] The POM for org.rhq:safe-invoker:jar:4.14.0-SNAPSHOT is missing, no dependency information available
[WARNING] The POM for org.rhq:rhq-common-drift:jar:4.14.0-SNAPSHOT is missing, no dependency information available
[WARNING] The POM for org.rhq:rhq-server-metrics:jar:4.14.0-SNAPSHOT is missing, no dependency information available
[WARNING] The POM for org.rhq:rhq-cassandra-util:jar:4.14.0-SNAPSHOT is missing, no dependency information available
[WARNING] The POM for org.rhq:rhq-jboss-as-dmr-client:jar:4.14.0-SNAPSHOT is missing, no dependency information available
[WARNING] The POM for org.rhq:test-utils:jar:4.14.0-SNAPSHOT is missing, no dependency information available
[WARNING] The POM for org.rhq.helpers:rest-docs-generator:jar:4.14.0-SNAPSHOT is missing, no dependency information available
[WARNING] The POM for org.rhq:rhq-core-domain:jar:tests:4.14.0-SNAPSHOT is missing, no dependency information available

Still no bueno with DocGen. :(

At this point, I hit a dead end. And when I hit a dead end, I start doing questionable things in hope that I can resolve the issue.

I thought perhaps the following step was wrong:

4) `$ cd modules/enterprise/server/jar`

I though to myself "Perhaps I need to execute $ mvn -Ddocgen install at the project root?"

I executed the command at project root and things certainly looked promising. Maven began downloading a whole stack of dependencies that related to the platform. But as a Maven n00b, I learned after 11 minutes that this was a false sense of security. By executing the DocGen command at the project root, maven took the configuration in the root pom.xml file and began compiling the entire project.

Should have trusted the instructions on that one. But the positive out of this was I got a refresher about how Maven works. Lets chalk this up to experience.

Build only what you need, at the level you need.

— a Maven Warlock Lvl10

Sagely advice for sure.

Fourth Attempt: Branch Not Master!

After contacting the RHQ team (overnight - very quick response), they could see that I was running these commands against master. It turns out I needed to run DocGen on a branch and not master. They also gave me the tip that I could cut down the build time by specifying -DskipTests and possibly -Dmaven.test.skip

Based on this feedback, I hypothesised the updated steps to be:

  1. $ yum install maven

  2. $ git clone https://github.com/rhq-project/rhq.git jon

  3. $ cd jon

  4. $ git checkout -b release/[latest_branch]

  5. $ cd modules/enterprise/server/jar

  6. $ mvn -Ddocgen compile -DskipTests -Dmaven.test.skip (initially, then for subsequent builds)

  7. $ mvn -Ddocgen install -DskipTests -Dmaven.test.skip

Still no bueno with DocGen. :(

I ran the compile command first, which failed. I then, out of desperation, ran the install command. It produced the same result:

[jmorgan@jmorgan-bne-redhat-com jar] (release/jon3.3.x) $ mvn -Ddocgen compile -DskipTests -Dmaven.test.skip
OpenJDK 64-Bit Server VM warning: ignoring option MaxPermSize=512m; support was removed in 8.0
[INFO] Scanning for projects...
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] Building RHQ Enterprise Server JAR 4.14.0-SNAPSHOT
[INFO] ------------------------------------------------------------------------
[WARNING] The POM for org.rhq:rhq-enterprise-comm:jar:4.14.0-SNAPSHOT is missing, no dependency information available
[WARNING] The POM for org.rhq:rhq-enterprise-server-xml-schemas:jar:4.14.0-SNAPSHOT is missing, no dependency information available
[WARNING] The POM for org.rhq:rhq-core-domain:jar:4.14.0-SNAPSHOT is missing, no dependency information available
[WARNING] The POM for org.rhq:rhq-core-plugin-api:jar:4.14.0-SNAPSHOT is missing, no dependency information available
[WARNING] The POM for org.rhq:rhq-core-client-api:jar:4.14.0-SNAPSHOT is missing, no dependency information available
[WARNING] The POM for org.rhq:rhq-core-dbutils:jar:4.14.0-SNAPSHOT is missing, no dependency information available
[WARNING] The POM for org.rhq:safe-invoker:jar:4.14.0-SNAPSHOT is missing, no dependency information available
[WARNING] The POM for org.rhq:rhq-common-drift:jar:4.14.0-SNAPSHOT is missing, no dependency information available
[WARNING] The POM for org.rhq:rhq-server-metrics:jar:4.14.0-SNAPSHOT is missing, no dependency information available
[WARNING] The POM for org.rhq:rhq-jboss-as-dmr-client:jar:4.14.0-SNAPSHOT is missing, no dependency information available
[WARNING] The POM for org.rhq.helpers:rest-docs-generator:jar:4.14.0-SNAPSHOT is missing, no dependency information available
[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 1.557 s
[INFO] Finished at: 2015-02-17T10:32:18+10:00
[INFO] Final Memory: 18M/437M
[INFO] ------------------------------------------------------------------------
[ERROR] Failed to execute goal on project rhq-enterprise-server: Could not resolve dependencies for project org.rhq:rhq-enterprise-server:ejb:4.14.0-SNAPSHOT: The following artifacts could not be resolved:
org.rhq:rhq-enterprise-comm:jar:4.14.0-SNAPSHOT,
org.rhq:rhq-enterprise-server-xml-schemas:jar:4.14.0-SNAPSHOT,
org.rhq:rhq-core-domain:jar:4.14.0-SNAPSHOT,
org.rhq:rhq-core-plugin-api:jar:4.14.0-SNAPSHOT,
org.rhq:rhq-core-client-api:jar:4.14.0-SNAPSHOT,
org.rhq:rhq-core-dbutils:jar:4.14.0-SNAPSHOT,
org.rhq:safe-invoker:jar:4.14.0-SNAPSHOT,
org.rhq:rhq-common-drift:jar:4.14.0-SNAPSHOT,
org.rhq:rhq-server-metrics:jar:4.14.0-SNAPSHOT,
org.rhq:rhq-jboss-as-dmr-client:jar:4.14.0-SNAPSHOT,
org.rhq.helpers:rest-docs-generator:jar:4.14.0-SNAPSHOT:
Failure to find org.rhq:rhq-enterprise-comm:jar:4.14.0-SNAPSHOT in https://oss.sonatype.org/content/repositories/snapshots/ was cached in the local repository, resolution will not be reattempted until the update interval of sonatype-snapshots has elapsed or updates are forced -> [Help 1]
[ERROR]

Fifth Attempt: Why Pre-requisites Matter in Docs

So, I got a response from the RHQ list and a key piece of info was missing:

You need to build RHQ first before you can build the API docs. You also need to do it on master, not release/jon3.3.x.

Some choice expletives were uttered by me at this point…​ This was not mentioned anywhere in the internal product doc repositories, in the originally-provided procedure, nor was it implied as a pre-requisite in the upstream docs.

The problem with not setting pre-requisites in documentation mean that if a user gets dumped here by Google, there was no context to say the project needs to be built first. Folks don’t read a book cover to cover any more. You need to cater for this by telling them basic information like this at every opportunity. Treach each page as page one.

Let’s revise the procedure with the updated information received today:

  1. $ yum install maven

  2. Build RHQ, which covers the following:

    1. Install JDK

    2. Install Maven

    3. Install Git

    4. Install and Create Database for PostgreSQL

  3. $ git clone https://github.com/rhq-project/rhq.git jon

  4. $ cd jon

  5. $ git checkout -b release/[latest_branch]

  6. $ cd modules/enterprise/server/jar

  7. $ mvn -Ddocgen compile -DskipTests -Dmaven.test.skip (initially, then for subsequent builds)

  8. $ mvn -Ddocgen install -DskipTests -Dmaven.test.skip

Still no bueno with DocGen. :(

Up until this point, I’ve spent two days on this task. I’ve decided to make lemonade out of my two-day-old lemons and correct the Generating Plugin Documentation community docs to reflect this. I also made changes to three other community pages linked from the Building RHQ page doc page with correct information for Fedora 21:

This info will surely prove valuable for community devs that want to experiment with RHQ.

The Actual (and correct) Process

This post is getting so long now, I think I’ll make a separate one.

There is still quite a path to traverse down before I can comfortably say "generating RHQ API docs is easy".

The BugZilla Bug I raised to capture these challenges will hopefully help the engineers with resolving the issue for me, and for users of the project.

And what’s even better is that I’ll be able to update the generation procedures for API documentation for the next time I need to pull the docs out.

comments powered by Disqus