Javadoc issues

[manuzhang]

Apache Iceberg version

main (development)

Query engine

None

Please describe the bug 🐞

There are several issues with Javadoc

1. https://iceberg.apache.org/javadoc/nightly is not found
2. Links in https://iceberg.apache.org/docs/1.4.3/metrics-reporting points to 1.5.2 Javadoc
3. https://iceberg.apache.org/docs/javadoc/1.5.2/org/apache/iceberg/rest/RESTMetricsReporter.html is missing (fixed in Docs: Point links in metrics-reporting.md to GitHub Java source #10397)

[jbonofre]

Good catch @manuzhang ! Let me fix that on the website.

[manuzhang]

@jbonofre Are you working on all these issues?

[jbonofre]

I didn't start yet. Up to you. I can start on it tonight or you can take it.

[Fokko]

Thanks for caching these @manuzhang. Let me know if you need any help!

[manuzhang]

Submitted #10397 for No. 3.

[Fokko]

https://iceberg.apache.org/javadoc/nightly is not found

It looks like the nightly points to latest according to https://github.com/apache/iceberg/tree/main/site#building-the-versioned-docs

[manuzhang]

It looks like the nightly points to latest according to https://github.com/apache/iceberg/tree/main/site#building-the-versioned-docs

It's documented but not actually implemented.

[Fokko]

Links in https://iceberg.apache.org/docs/1.4.3/metrics-reporting points to 1.5.2 Javadoc

That one is quite tricky. It looks like it uses the macro plugin to set the version. The problem is that the macro plugin doesn't work well with the monorepo plugin. There is no way to override the version. I think the easiest way to fix this is to change the directory structure from:

docs/1.4.3/
javadoc/1.4.3/

to:

1.4.3/docs/
1.4.3/javadoc/

This way we can make relative links. I can play around with this tomorrow

[Fokko]

I'll bump this to 1.7.0. It would be best if we could fix this using the macro plugin in combination with the monorepo plugin: backstage/mkdocs-monorepo-plugin#130

[jbonofre]

@Fokko thanks ! It makes sense. I will take a look on this one for 1.7.0 (definitely not a blocker for 1.6.0).

[RussellSpitzer]

@jbonofre Did you want to work on this?

[jbonofre]

@RussellSpitzer sure thing ! I will ! Thanks !

[jbonofre]

Sorry I forgot this one. I can take a look later tonight or tomorrow morning my time.

[manuzhang]

@jbonofre Have you got a chance to fix javadoc (issue No.1)?

[jbonofre]

I took a quick look on (1): I think the only thing missing is to add in the site/dev/common.sh a symbolic link nightly on the javadoc version fetch by git worktree add -f docs/javadoc. Basically, symlink on the latest javadoc fetch version with nightly.
I'm testing locally, I will open a PR soon.

[jbonofre]

I'm resuming work on this one to include 1.7.2 and 1.8.0.