Update scaladoc docs

[BarkingBad]

Could you take a look @julienrf? I will update docs.scala-lang New features for Scaladoc chapter after dotty nightly will be published with the docs so I could point them here.

[BarkingBad]

https://scala3doc.virtuslab.com/pr-version-browser-docs/scala3/docs/usage/scaladoc/changing-versions.html
https://scala3doc.virtuslab.com/pr-version-browser-docs/scala3/docs/usage/scaladoc/settings.html

In case of colourings are wrong check if this action completed OK (it is still running when I'm writing it), but I see they are OK at my local copy

[vincenzobaz]

I am very excited about this feature, especially for the simplicity of having a JSON with URLs. I was experimenting with Docusaurus which also has a similar mechanism relying on making copies of folders.

From this doc it is not clear to me how we should treat the JSON document. For example, if I reuse your example:

{
  "versions": {
    "3.0.X": "https://dotty.epfl.ch/3.0.X/docs/index.html",
    "Nightly": "https://dotty.epfl.ch/docs/index.html"
  }
}

Does this fille need to be present in both https://dotty.epfl.ch/3.0.X/ and https://dotty.epfl.ch/? In other words, when we generate a new version of the site, do we need to propagate the new JSON to the old folder in order to have the same menu in both sites?

[BarkingBad]

Good point, I will elaborate this topic in the docs then. The general idea is that you keep only one JSON file that should be broadly available across the web at given url, let's say http://my.page/my_json.json. Now when you create docs you should pass this url with setting -versions-dictionary-url http://my.page/my_json.json. The docs will do dynamic Ajax call to retireve the json and feed the drop down menu. If you have, for example, 3 different docs they all should have been generated with this setting. This enable you to generate 4th docs and just update JSON file without changing its location. The drawback is that you have to prepare location for JSON file before generating the first docs, but I guess, if you are able host web page, you can as well just drop the json file somewhere top-level at your hosting domain.

[vincenzobaz]

Thank you for clarifying @BarkingBad!
So there is only one JSON at a fixed and known address which is updated when a new version is released.
My first remark is that this address should be written in a single place for each "site" so that it can be easily modified, for example a siteConfig.json (again drawing inspiration from docusaurus), with the -versions-dictionary-url writing to this file.

I already see myself writing regexps to change the URL because something changed in my build 😆

This config file could be the beginning of the customization story of sites: fonts, css paths, vcs links etc

[vincenzobaz]

Thank you for documenting this very useful feature

[BarkingBad]

Currently, the link is embedded into HTML head metadata. It should not be that hard to connect it via the intermediate JSON, though we could make convention out of it, and decide that the siteConfig.json can appear at top-level of each documentation respectively and should be read in such case, then we should not pass any setting, just fill in correctly the config json.

Unfortunately I have little time recently (I'm finishing things at the university) so if you'd like to contribute feel free, though I'm not sure that we need all the configuration stuff with css etc., albeit I see your concerns with changing build.

[julienrf]

Thank you, I agree with Vinenzo’s suggestions and I have added a couple of other remarks.

[BarkingBad]

Hi, sorry for absence, I was busy with my university exams. I applied your suggested changes. I hope I covered all the problems and we could merge it.

[julienrf]

Thank you @BarkingBad!