I opened up https://github.com/apache/beam/pull/8588 with the changes listed above.
On Mon, May 13, 2019 at 5:17 PM Ankur Goenka <[email protected]> wrote: > Given that this simplifies the release process and keeps the javadocs upto > date., IMO this looks to be a good tradeoff. > > *From: *Lukasz Cwik <[email protected]> > *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 <[email protected]> >> *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 <[email protected]> >>> *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 <[email protected]> >>>> *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 <[email protected]> >>>>> *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 >>>>>> >>>>>
