Can javadoc be generated separately from the code build? Wondering if it'd be more efficient to have a separate job that just builds javadocs
FTR: This may or may not re-use https://git.opendaylight.org/gerrit/#/c/60213/
From: Helpdesk for the OpenDaylight project via RT <helpdesk@opendaylight.org>
Date: Tue, Sep 26, 2017 at 6:28 PM
Subject: opendaylight.org #46266 AutoReply: ODLPARENT-124 https://nexus.opendaylight.org/content/sites/javadoc, instead of /site
To: vorburger@redhat.com
Your support ticket regarding:
"ODLPARENT-124 https://nexus.opendaylight.org/content/sites/javadoc, instead of /site",
has been entered in our ticket tracker. A summary of your ticket appears below.
-------------------------------------------------------------------------
Thanh,
as just discussed during the Kernel project's call, I'm opening this ticket
for working with you on https://bugs.opendaylight.org/show_bug.cgi?id=9215,
and as first step of that request that you create a new
https://nexus.opendaylight.org/content/sites/javadoc, instead of /site, so
that in
https://github.com/opendaylight/odlparent/blob/master/deploy-site.xml we
can push to that.
> Can javadoc be generated separately from the code build?
Yep! If you do "mvn clean javadoc:aggregate -V -B", as in https://git.opendaylight.org/gerrit/#/c/60213/, on the root of e.g. odlparent (or any other project), then you can "xdg-open target/site/apidocs/index.html" and get a nice JavaDoc of that entire project - without having had to build that project's code/tests.
> Wondering if it'd be more efficient to have a separate job that just builds javadocs
We could, if you prefer [personally I just want to finally get a JavaDoc site... ;-)] BUT it's important to understand that we HAVE to run the javadoc Maven plugin (which BTW isn't our biggest problem in terms of build time performance, if that is what you're after?) during normal builds as well, because:
(a) it produces the per artifact attached JavaDoc JAR, required for IDEs
(b) it validates (to some degree; not great, but still) that you don't completely screw up the JavaDoc of code changes
So basically we could have a separate job in theory, in addition to running Javadoc during code build, but in practice I don't think it gives us anything useful - so I would propose we keep it as is, if that works for you?
Thanh, do you mind if I assign this issue to you? You can re-assign it back to me afterwards, but for now waiting on you (no stress!) with LF Helpdesk ticket #46266 to be able to then merge https://git.opendaylight.org/gerrit/#/c/63532/ (+1 from you?) and see if a JavaDoc will show up on https://nexus.opendaylight.org/content/sites/javadoc/master/org.opendaylight.odlparent (right?) ... if it does, then we only need DOCS-33 and probably some time also RELENG-62 and then we're done here with this issue! Then I'll start proposing the equivalent of c/63532 to other projects like netvirt or genius and others...
(In reply to Michael Vorburger from comment #4)
> Thanh, do you mind if I assign this issue to you?
Not a problem. I'll start poking at this today now that Nitrogen is out the door.
(In reply to Michael Vorburger from comment #3)
> > Can javadoc be generated separately from the code build?
> Yep!
Great!
> > Wondering if it'd be more efficient to have a separate job that just builds javadocs
>
> We could, if you prefer [personally I just want to finally get a JavaDoc
> site... 
] BUT it's important to understand that we HAVE to run the
> javadoc Maven plugin (which BTW isn't our biggest problem in terms of build
> time performance, if that is what you're after?) during normal builds as
> well, because:
>
> (a) it produces the per artifact attached JavaDoc JAR, required for IDEs
>
> (b) it validates (to some degree; not great, but still) that you don't
> completely screw up the JavaDoc of code changes
>
> So basically we could have a separate job in theory, in addition to running
> Javadoc during code build, but in practice I don't think it gives us
> anything useful - so I would propose we keep it as is, if that works for you?
Understood. However the way the jobs are designed right now it looks like it will run the full build with the javadoc maven plugin and then in a post builder it will again run "javadoc:aggregate" again. So the way the jobs are currently designed it looks like it will run the javadoc stuff twice anyway. So I think separating it out will save us time anyway.
A quick test on my local system I found the following job times:
odlparent: 2m30s
mdsal: 5m30s
yangtools: 2m
So I think we will save a little time. Regardless of that though what I was thinking more about is simplifying the jobs. If we made javadoc verify & merge separate jobs we could simplify the java-merge job template and make it easier for us to respin javadocs if we need to. We can also allow the verify job to store on the log server a copy of the generated javadoc
Additionally we'll be able to phase in the new javadocs and phase out the old maven-site (the current patch proposed will switch the jobs to building javadocs for everyone and break maven-site generation so there's no phasing here).
How about this, let me take this up as my action item to create the new javadoc templates. If I can finish them this week we can start deploying them next week. This will take a little longer but I think we can give a better user experience and I'm willing to do the legwork here.
> able to phase in the new javadocs and phase out the old maven-site
> (the current patch proposed will switch the jobs to building javadocs for
> everyone and break maven-site generation so there's no phasing here)
Just FTR: Personally I think that's a complete non-issue (as sites are not used at all anyway), but Robert suggested in yesterday's Kernel Meeting that we this staged like that, so if you're willing to do the extra work - sure, go for it.
> How about this, let me take this up as my action item to create (...)
> (...) better user experience and I'm willing to do the legwork here.
Yes!! Please. Thank you!
Ok so I made a new job in global-jjb to deploy the new javadoc jobs.
https://gerrit.linuxfoundation.org/infra/6576
This patch provides 2 new jobs:
1.
{project-name}-maven-javadoc-verify-{stream}2. {project-name}
maven-javadoc-publish
The first one runs on verify when a new Gerrit patch is submitted for review while the 2nd one runs once a patch is merged and does the additional task of pushing the javadocs to Nexus.
An example of the verify job run is available here on the log server and includes the the generated javadoc fully viewable:
https://logs.opendaylight.org/sandbox/jenkins091/odlparent-maven-javadoc-verify-master/6/
The 2nd job does the same thing as the verify job but additionally pushes them to the javadoc repo in Nexus. Example here:
https://nexus.opendaylight.org/content/sites/javadoc/
The jobs can be activated by any project by adding the '
{project-name}-maven-javadoc-jobs' job group to their project declaration once global-jjb is released with this patch.
With global-jjb v0.9.0 deployed I've pushed this https://git.opendaylight.org/gerrit/63885 which once merged will enable our first POC.
This work is complete now.