Generate downloadable version of javadocs documentation in website deploy script

[boughtonp]

Jetty version(s)
all

Description

As per discussion on mailing list, please update the script that generates https://www.eclipse.org/jetty/javadoc/ to also create a downloadable archive for current/supported versions of Jetty.

[joakime]

Most IDEs will provide the javadocs natively if you are using the Jetty dependencies from any build tool (of many) or build repository (of many).

The javadoc's are already available on Maven Central for every artifact that is present on Maven Central - a feature that is mandated by Maven Central btw.

Our aggregate javadoc does not contain everything that exist as produced by Jetty on Maven Central.
The javadoc on https://www.eclipse.org/jetty/javadoc/ is no exception to this.

The only true javadoc is the per-artifact javadoc which is based on what features you actually use from Jetty.

See the list of exclusions in the aggregate javadoc build.
https://github.com/eclipse/jetty.project/blob/jetty-11.0.12/javadoc/pom.xml#L79-L123

Nobody (and I do mean nobody) can use 100% of Jetty, it's an impossible scenario that would cause conflicts at startup time.
There's no such thing as an "all" or "full" or "complete" Jetty release, so as a consequence there's no such thing as a complete javadoc either (the javadoc tooling in Java will actually fail if this is attempted)

[joakime]

This will become even more ridiculous with Jetty 12.
I don't think we can have the ENV sub-sections present in the same Javadoc at all (too many conflicting names at different versions).

[joakime]

@jmcc0nn3ll its a shame we can't just deploy the /javadoc/ project to maven central (the maven central rules will reject it as it contains references to classes that are not in the non-javadoc jar)

[joakime]

@jmcc0nn3ll we have a /org/eclipse/jetty/documentation/ groupId already, perhaps we should revive it and have it be a pom project that just builds a zip including the adoc and javadoc aggregate during the build?

[boughtonp]

This isn't one of those "I want full Jetty" requests.

I use jetty-home (in home/base setup), and when I'm trying to do something new I first check the regular documentation, but this is frequently incomplete or references the relevant class in the online javadoc, where further details can often by found.

Thus I want to also be able to read those pages when offline, and assumed there would already be an archive to download I just wasn't finding.

If there are hidden complexities, I can use either wget or httrack to crawl those pages.

[joakime]

so far today, i've tried ...

Making jetty-home have an optional -with-docs classified object with the adocs + javadocs.

• This isn't possible, as it introduces a circular dependency loop [ERROR] The projects in the reactor contain a cyclic reference: Edge between 'Vertex{label='org.eclipse.jetty:javadoc:10.0.13-SNAPSHOT'}' and 'Vertex{label='org.eclipse.jetty:jetty-maven-plugin:10.0.13-SNAPSHOT'}' introduces to cycle in the graph org.eclipse.jetty:jetty-maven-plugin:10.0.13-SNAPSHOT --> org.eclipse.jetty:jetty-home:10.0.13-SNAPSHOT --> org.eclipse.jetty:javadoc:10.0.13-SNAPSHOT --> org.eclipse.jetty:jetty-maven-plugin:10.0.13-SNAPSHOT @

I've tried to make /javadocs/ publish to maven central.

• This is rejected by maven central due to the mismatch in javadoc.jar to jar file contents (there's a class to javadoc check that's not allowing it)
• Even tried setting it to <packaging>pom</packaging> but the existence of the javadoc.jar is confusing the central requirements.

I've tried making a /jetty-project/ have the documentation artifacts.

• This is rejected by Maven as it introduces another circular dependency loop. (everything to everything)

[joakime]

Perhaps making the /javadocs/ artifact not a jar file (eg: a zip or tar.gz) should skip the maven central requirements?
AND perhaps fix the circular dependency loop?

[gregw]

Thus I want to also be able to read those pages when offline, and assumed there would already be an archive to download I just wasn't finding

Whilst we seek the best way to make such a javadoc aggregate easily accessible....
a simple way to get the javadoc offline is to checkout the source and build the javadoc:javadoc target. Note also that your IDE should be able to download all the javadocs for your projects dependencies.

[jmcc0nn3ll]

Thus I want to also be able to read those pages when offline, and assumed there would already be an archive to download I just wasn't finding

Whilst we seek the best way to make such a javadoc aggregate easily accessible.... a simple way to get the javadoc offline is to checkout the source and build the javadoc:javadoc target. Note also that your IDE should be able to download all the javadocs for your projects dependencies.

This is why we can do it when we generate the Javadoc for the website, we have it right there, just tarball it and link it on the downloads page.

[olamy]

maybe we should revert this change see #10312