Broken source links in library documentation

[SamB]

The source links from the Scala 3 library documentation on scala.org are broken, at least for version 3.1.3.

For example, https://scala-lang.org/api/3.1.3/scala/Int.html links to https://github.com/lampepfl/dotty/blob/3.1.3/out/bootstrap/stdlib-bootstrapped/scala-3.1.3-bin-SNAPSHOT-nonbootstrapped/src_managed/main/scala-library-src/scala/Int.scala#L26, but that gives 404.

Hmm. I had hoped that some git repositories had just been shuffled about and you just needed to copy some tags over or something, but now I see that this link points into the out/ tree, so I guess actual surgery on the HTML would be required if you want to fix this for existing releases, unless the configuration to generate the docs for scala.org is stored out-of-tree to begin with?

(It would be unfortunate for the version on scala.org to be different from the version obtained by building from source, if that is not normally the case. A necessary evil?)

I thought the links in the Nightly library docs were okay, but after a closer look I'm not so sure: https://dotty.epfl.ch/api/scala/Int.html links to https://github.com/scala/scala/blob/v2.13.8/src/library/scala/Int.scala#L26 of all places. Is that correct?

[KacperFKorban]

I think that it's just a configuration issue with the generated docs for 3.1.3.

For https://dotty.epfl.ch/api/scala/Int.html to point to https://github.com/scala/scala/blob/v2.13.8/src/library/scala/Int.scala#L26 is the correct behavior. Notice that there are no sources for classes from Scala 2 stdlib duplicated in the dotty repository i.e. the stdlib for Scala 3 combines sources from scala/scala and lampepfl/dotty repos.

[Dedelweiss]

Hello, Whether it's for this Issue or the one associated with the mention, I have the impression that it only concerns version 3.2.2 of the documentation. Indeed, during my tests I notice that this is fixed for the nightly version. Is there anything left to do for this issue? Thank you

[julienrf]

The website at https://dotty.epfl.ch is generated with different settings than the API documentation published at https://scala-lang.org/api/3.x. It is possible that the API documentation is still not fixed. @szymon-rd how do you generate the API documentation published at https://scala-lang.org/api/3.x?

[julienrf]

I tried locally running the sbt task scaladoc/generateStableScala3Documentation 3.3.0 from the tag 3.3.0. I guess this is what you do during the release process? (It would be really beneficial to document that)

The result produces API documentation with incorrect links… The URL contains a reference to version 3.3.1-RC1 such as: https://github.com/lampepfl/dotty/blob/3.3.0/out/bootstrap/stdlib-bootstrapped/scala-3.3.1-RC1-bin-SNAPSHOT-nonbootstrapped/src_managed/main/scala-library-src/scala/Array.scala#L658

But if I run the same command from main (and with 3.3.1-RC1 as version number) then the source links are correct.

[julienrf]

Well, now that the API documentation has been published I can see that its source links are correct. However, it is still unclear to me what command you invoked to get them right, do you mind documenting that here? https://dotty.epfl.ch/docs/contributing/procedures/release.html Maybe @Florian3k could help?

[szymon-rd]

@julienrf It's just the

sbt "scaladoc/generateStableScala3Documentation 3.3.0"

When checked out to the 3.3.0 tag

[julienrf]

This is weird because that’s precisely what I tried (see my comment above) and that didn’t work for me. Anyway, would it be possible to update the release docs with this information?

[szymon-rd]

We will do that in this issue: https://github.com/lampepfl/dotty/issues/17736

[julienrf]

Thank you, then I am closing this issue.