Re: Do we maintain offline artifact version in javadocs sdks/java/javadoc/build.gradle
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 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 > *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/8cc7c53139d0eecad0ec994b9a313cf31645 >> >> From a Javadoc correctness and maintenance point of view, this seems much >> simpler overall to me. >> >> >> *From: *Lukasz Cwik >> *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 >>> *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 *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 > *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 >> >
Re: Do we maintain offline artifact version in javadocs sdks/java/javadoc/build.gradle
Given that this simplifies the release process and keeps the javadocs upto date., IMO this looks to be a good tradeoff. *From: *Lukasz Cwik *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/8cc7c53139d0eecad0ec994b9a313cf31645 > > From a Javadoc correctness and maintenance point of view, this seems much > simpler overall to me. > > > *From: *Lukasz Cwik > *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 >> *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 >>> *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 *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 >
Re: Do we maintain offline artifact version in javadocs sdks/java/javadoc/build.gradle
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/8cc7c53139d0eecad0ec994b9a313cf31645 >From a Javadoc correctness and maintenance point of view, this seems much simpler overall to me. *From: *Lukasz Cwik *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 > *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 >> *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 >>> *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 >>>
Re: Do we maintain offline artifact version in javadocs sdks/java/javadoc/build.gradle
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 *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 > *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 >> *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 >>> >>
Re: Do we maintain offline artifact version in javadocs sdks/java/javadoc/build.gradle
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 *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 > *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 >> >
Re: Do we maintain offline artifact version in javadocs sdks/java/javadoc/build.gradle
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 *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 >
Do we maintain offline artifact version in javadocs sdks/java/javadoc/build.gradle
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
