Update javadoc to SNT v4

[carshadi]

📚 Documentation

The API docs at https://morphonets.github.io/SNT (which redirects to https://javadoc.scijava.org/Fiji/index.html?sc/fiji/snt/package-summary.html) are still outdated on version 3.2.9

[carshadi]

what would be the proper way to do this? Create a new workflow that triggers on release and run the scijava-scripts javadoc generator ? pinging @ctrueden , @tferr

[ctrueden]

The javadoc for https://javadoc.scijava.org/Fiji is derived from https://github.com/fiji/fiji-javadoc. So all you need to do is add an SNT dependency to that pom.xml file. However, SNT is not part of Fiji, so it may not make sense to keep it at that URL.

A service I really like is javadoc.io, which lets you browse javadocs for any project published properly to Maven Central. Unfortunately, we still have many things published only to maven.scijava.org, including SNT and many of its dependencies. So javadoc.io won't help us yet. And unfortunately, javadoc.io's infrastructure does not appear to be open source, so we cannot self-host for our own artifacts on maven.scijava.org. See also scijava/pom-scijava#130 for some related information.

So then the question is: for the time being, what URL would make the most sense for SNT? Options which occur to me:

1. Add a dedicated SNT icon to javadoc.scijava.org with the SNT javadocs. This would be similar to projects like BoneJ, which do this now (model your config after e.g. fiji-javadoc or https://github.com/bonej-org/bonej-javadoc). Add SNT to the pom-scijava-base javadoc links config (unfortunately, the more links we have here, the slower javadoc builds go for everyone).
2. Change javadoc.scijava.org to be a giant mashup of all the SciJava community javadocs including ImageJ, ImageJ2, ImgLib2, SCIFIO, Fiji, and extensions thereof, including SNT.
3. Implement/deploy some javadoc.io-like thing on javadoc.scijava.org that supports versioned javadoc for all projects that publish a -javadoc.jar (which is any project extending pom-scijava).

Option (1) is straightforward, but requires creation of an SNT-javadoc repo or similar. Option (2) is easiest, but maybe confusing because it introduces non-Fiji classes into the Fiji subtree. Option (3) would be nice, but might be too much work (not sure without researching it further).

[carshadi]

Option 1 sounds reasonable to me, I like how the BoneJ API is isolated, as it is easier to navigate compared to having all of Fiji there too. @tferr thoughts?

[ctrueden]

I created morphonets/SNT-javadoc and hooked it up to javadoc.scijava.org.

@tferr If you like this, the only action needed is to file a PR to scijava/javadoc.scijava.org adding the SNT project icon with link to https://javadoc.scijava.org/SNT (which now exists).

If you would prefer to generalize these javadocs across more of the Morphonets project, we could instead change it to https://javadoc.scijava.org/Morphonets, and rename the repository to morphonets/morphonets-javadoc, and mix in more components to the list in its pom.xml. You would also need to change the .github/build.sh to name the project Morphonets instead of SNT, and do some other renames of SNT ➡️ Morphonets in the pom.xml.

[tferr]

Yes option 1 sounds the best. Thanks a lot @ctrueden. super neat that it is working already. Questions:

1. I noticed that some links pointing to the docs of other dependencies are not working: e.g., the link to the RAI documentation in this constructor. In this case, the link points to https://javadoc.scijava.org/Fiji/net/imglib2/RandomAccessibleInterval.html?is-external=true, but should be pointing to
   https://javadoc.scijava.org/ImgLib2/net/imglib2/RandomAccessibleInterval.html?is-external=true. Is there a way to fix it?
2. Related to the previous, links to the ImageJ1 are not functional. Would be nice to have them working
   (these are all minor things).

OK, will start the PR for the icon. @ctrueden, did you know that the icon is generated programmatically? pretty nerdy stuff. When lack of graphic design skills becomes a feature not a bug :)

[tferr]

@ctrueden , @carshadi , just submitted the PR. let's include only SNT for now, rather than generalizing to the remaining morphonets projects, since the javadocs for those is really scarse for now.

[ctrueden]

I merged the PR. Thanks!

I noticed that some links pointing to the docs of other dependencies are not working...Is there a way to fix it?

It's a weird problem. I have a vague memory of seeing it before, but never figured out what's causing the issue. I filed an issue for it: scijava/javadoc.scijava.org#12

links to the ImageJ1 are not functional.

Issue tracked here: scijava/javadoc.scijava.org#9

[carshadi]

Yay, big thanks @ctrueden. I'll go ahead and close this.