Given that this simplifies the release process and keeps the javadocs upto date., IMO this looks to be a good tradeoff.
*From: *Lukasz Cwik <lc...@google.com> *Date: *Mon, May 13, 2019 at 5:09 PM *To: *dev While I was looking for the latest versions of docs, I found > http://javadoc.io. It fetches the javadoc from Maven central and unpacks > that jar displaying its contents to users. This means that we could make > all our non Apache Beam javadoc links goto javadoc.io instead of trying > to find the official project website that maintains them (which sometimes > there isn't one or they only have the javadoc for the latest). > > Has anyone had experience using javadoc.io in the past? > Would there by any concerns about swapping to use javadoc.io instead of > the official versions hosted on project pages? > > I have an example commit here: > https://github.com/lukecwik/incubator-beam/commit/94a97fbc83883496feae071cc44689f5fb2f5743 > You can generate the aggregate javadoc via "./gradlew -p sdks/java/javadoc > aggregateJavadoc" which builds > "./sdks/java/javadoc/build/docs/javadoc/index.html" > > If people are happy with javadoc.io, should we migrate from using > offlinelinks to links so we don't have to maintain the package lists in > https://github.com/apache/beam/blob/master/sdks/java/javadoc/? > This would mean that we would be able to just enumerate all the > dependencies we have in Apache Beam and generate all the javadoc without > maintaining a list of packages or dependencies. It would mean that you > would need to have an internet connection to build the aggregated javadoc > because the javadoc tool would need to fetch the package-list files from > javadoc.io. The delta for that change is > https://github.com/lukecwik/incubator-beam/commit/8cc7c53139d0eecad0ec9945555b9a313cf31645 > > From a Javadoc correctness and maintenance point of view, this seems much > simpler overall to me. > > > *From: *Lukasz Cwik <lc...@google.com> > *Date: *Mon, May 13, 2019 at 1:39 PM > *To: *dev > > I see. We should be able to fix that to do what we do when we embed the >> versions of dependencies in our Maven archetypes like so[1]: >> dependencies.create(project.library.java.google_api_client).getVersion() >> >> I'll send out a PR updating the javadoc pulling to be based off the >> version and open up a PR. >> >> 1: >> https://github.com/apache/beam/blob/abece47cc1c1c88a519e54e67a2d358b439cf69c/sdks/java/maven-archetypes/examples/build.gradle#L29 >> >> *From: *Kenneth Knowles <k...@apache.org> >> *Date: *Mon, May 13, 2019 at 11:57 AM >> *To: *dev >> >> I expect Ankur is referring to the hardcoded linkOffline bits here: >>> https://github.com/apache/beam/blob/master/sdks/java/javadoc/build.gradle#L78 >>> since >>> the versions are in the URLs, and also the downloaded files used are from >>> those versions. This helps with flakiness, since otherwise it has to >>> download stuff to figure out which identifiers are linkable. >>> >>> Kenn >>> >>> *From: *Lukasz Cwik <lc...@google.com> >>> *Date: *Mon, May 13, 2019 at 9:04 AM >>> *To: *dev >>> >>> What is the difference between the two files you are referring to? >>>> >>>> Note that sdks/java/javadoc/build.gradle is meant to produce one giant >>>> javadoc across many modules that users would be interested in >>>> (core/extensions/io/...) meant to be published on the website. >>>> >>>> *From: *Ankur Goenka <goe...@google.com> >>>> *Date: *Fri, May 10, 2019 at 5:21 PM >>>> *To: *dev >>>> >>>> Hi, >>>>> >>>>> I see that the sdks/java/javadoc/build.gradle is not in sync with >>>>> org/apache/beam/gradle/BeamModulePlugin.groovy . >>>>> I wanted to check if we are maintaining or not based on that we can >>>>> either remove or update sdks/java/javadoc/build.gradle. >>>>> >>>>> Thanks, >>>>> Ankur >>>>> >>>>
