Scaladoc generates broken local links

[dixine55]

As of currently, when you generate documentation for your library, the links that are generated are not clickable locally. I believe that this is due to that the network request made by jQuery is denied because of a CORS error, which is seen in the network tab.

Compiler version

sbt:> print scalaVersion 3.3.0

Minimized code

scala-cli doc . sbt doc

Both generations will lead to broken local links, I have not been able to generate it and try with Scaladoc directly, no matter what I've attempted as an arg to Scaladoc I get "The system cannot find the path specified.", but since both scala-cli and sbt doc are based on Scaladoc I feel pretty confident it's an issue with Scaladoc itself.

Output

Directory with packageName/ fonts/ hljs/ images/ scripts/ styles/ webfonts/ packageName.html favicon.ico index.html scaladoc.version (3.3.0)

And when you open packageName.html or index.html or any of the html files in packageName/* the linking doesn't work.

Expectation

I believe it should work out of the box, or it feels really weird for it not to..

But, in order to fix it I made this code that does almost patch all the links perfectly, I tried to understand how Scaladoc works by itself, but it's over my paygrade.

So if it is a bug and/or if we could add it as a feature to build it locally by passing an argument -local, that'd be very helpful to people that don't know how to boot up a webserver and configure headers.

Link to the program that fixes the links: https://github.com/dixine55/Scaladoc-Local-Version-Patcher

Edit; As som-snytt pointed out I missspelled Scaladoc as scalaDoc, changed it so it's consistent.

[som-snytt]

how scalaDoc works

Someone will say "Scaladoc", so it might as well be me. I don't know why it departs from "JavaDoc".

I don't know why an option would be needed, in the sense that URLs should just work. Scaladoc tool is always unexpectedly complex. I would expect the complexity at runtime, to support its useful features.

[dixine55]

@som-snytt Thank you for pointing out that inconsistency, fixed it now!

I agree that it'd be good if it worked straight out of the box, but as I haven't really developed a good enough understanding of how the code interacts in the grand scheme of things I was suggesting the "-local" option in case there is no "two world"-solution where it works both for local and online deployment right away.

I assume that the majority who use the tool will end up uploading it online anyway and therefore wouldn't want to tweak around too much with it, but then again, there's also cases where you want to try building it locally first..

[bjornregnell]

I think it should "Just work" out of the box for both local and server deployment, if possible, without any configs etc. If configs are needed it should work out of the box with no config for local usage and then require setting/config for server deployment. This is best because local usage is the simplest use case for beginners.

[bjornregnell]

BTW: Many thanks @dixine55 for fixing a simple-to-use workaround. This will help many students of Scala!

[SethTisue]

seems related? https://github.com/lampepfl/dotty/discussions/18903