OpenDaylight JIRA

OpenDaylight JIRA https://jira.opendaylight.org This file is an XML representation of an issue en-us

8.20.10

820010

22-06-2022

[ODLPARENT-124] POC odlparent's JavaDoc on javadoc.opendaylight.org (and then afterwards replicate this to get all ODL projects on it) https://jira.opendaylight.org/browse/ODLPARENT-124 odlparent Operating System: All Platform: All ODLPARENT-124

POC odlparent's JavaDoc on javadoc.opendaylight.org (and then afterwards replicate this to get all ODL projects on it)

Improvement Resolved Done Thanh Ha (zxiiro) Michael Vorburger Tue, 26 Sep 2017 16:21:47 +0000 Wed, 24 Jan 2018 14:28:03 +0000 Tue, 28 Nov 2017 15:22:55 +0000 3.0.2 General 0 1 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 <a href="https://git.opendaylight.org/gerrit/#/c/60213/" class="external-link" target="_blank" rel="nofollow noopener">https://git.opendaylight.org/gerrit/#/c/60213/</a> From: Helpdesk for the OpenDaylight project via RT <helpdesk@opendaylight.org> Date: Tue, Sep 26, 2017 at 6:28 PM Subject: <a href="#46266" target="_blank" rel="noopener">opendaylight.org #46266</a> AutoReply: <a href="https://jira.opendaylight.org/browse/ODLPARENT-124" title="POC odlparent's JavaDoc on javadoc.opendaylight.org (and then afterwards replicate this to get all ODL projects on it)" class="issue-link" data-issue-key="ODLPARENT-124"><del>ODLPARENT-124</del></a> <a href="https://nexus.opendaylight.org/content/sites/javadoc" class="external-link" target="_blank" rel="nofollow noopener">https://nexus.opendaylight.org/content/sites/javadoc</a>, instead of /site To: vorburger@redhat.com Your support ticket regarding: "<a href="https://jira.opendaylight.org/browse/ODLPARENT-124" title="POC odlparent's JavaDoc on javadoc.opendaylight.org (and then afterwards replicate this to get all ODL projects on it)" class="issue-link" data-issue-key="ODLPARENT-124"><del>ODLPARENT-124</del></a> <a href="https://nexus.opendaylight.org/content/sites/javadoc" class="external-link" target="_blank" rel="nofollow noopener">https://nexus.opendaylight.org/content/sites/javadoc</a>, 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 <a href="https://bugs.opendaylight.org/show_bug.cgi?id=9215" class="external-link" target="_blank" rel="nofollow noopener">https://bugs.opendaylight.org/show_bug.cgi?id=9215</a>, and as first step of that request that you create a new <a href="https://nexus.opendaylight.org/content/sites/javadoc" class="external-link" target="_blank" rel="nofollow noopener">https://nexus.opendaylight.org/content/sites/javadoc</a>, instead of /site, so that in <a href="https://github.com/opendaylight/odlparent/blob/master/deploy-site.xml" class="external-link" target="_blank" rel="nofollow noopener">https://github.com/opendaylight/odlparent/blob/master/deploy-site.xml</a> 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 <a href="https://git.opendaylight.org/gerrit/#/c/60213/" class="external-link" target="_blank" rel="nofollow noopener">https://git.opendaylight.org/gerrit/#/c/60213/</a>, 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 <a href="https://git.opendaylight.org/gerrit/#/c/63532/" class="external-link" target="_blank" rel="nofollow noopener">https://git.opendaylight.org/gerrit/#/c/63532/</a> (+1 from you?) and see if a JavaDoc will show up on <a href="https://nexus.opendaylight.org/content/sites/javadoc/master/org.opendaylight.odlparent" class="external-link" target="_blank" rel="nofollow noopener">https://nexus.opendaylight.org/content/sites/javadoc/master/org.opendaylight.odlparent</a> (right?) ... if it does, then we only need <a href="https://jira.opendaylight.org/browse/DOCS-33" title="javadoc.opendaylight.org" class="issue-link" data-issue-key="DOCS-33"><del>DOCS-33</del></a> and probably some time also <a href="https://jira.opendaylight.org/browse/RELENG-62" title="deploy-site.xml should wipe prior content on https://nexus.opendaylight.org/content/sites/site/" class="issue-link" data-issue-key="RELENG-62"><del>RELENG-62</del></a> 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... <img class="emoticon" src="https://jira.opendaylight.org/images/icons/emoticons/wink.png" height="16" width="16" align="absmiddle" alt="" border="0"/>] 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. <a href="https://gerrit.linuxfoundation.org/infra/6576" class="external-link" target="_blank" rel="nofollow noopener">https://gerrit.linuxfoundation.org/infra/6576</a> This patch provides 2 new jobs: 1. {project-name}-maven-javadoc-verify-{stream} 2. {project-name} <del>maven-javadoc-publish</del> {stream} 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: <a href="https://logs.opendaylight.org/sandbox/jenkins091/odlparent-maven-javadoc-verify-master/6/" class="external-link" target="_blank" rel="nofollow noopener">https://logs.opendaylight.org/sandbox/jenkins091/odlparent-maven-javadoc-verify-master/6/</a> The 2nd job does the same thing as the verify job but additionally pushes them to the javadoc repo in Nexus. Example here: <a href="https://nexus.opendaylight.org/content/sites/javadoc/" class="external-link" target="_blank" rel="nofollow noopener">https://nexus.opendaylight.org/content/sites/javadoc/</a> 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 <a href="https://git.opendaylight.org/gerrit/63885" class="external-link" target="_blank" rel="nofollow noopener">https://git.opendaylight.org/gerrit/63885</a> which once merged will enable our first POC. This work is complete now. Blocks DOCS-33 RELENG-62 Development External issue ID 9215 External issue URL Rank 0|i023gf: