Add browsable versions extension for scaladoc #12596

BarkingBad · 2021-05-25T13:40:54Z

No description provided.

pikinier20 · 2021-05-27T06:52:53Z

scaladoc-js/src/versions-dropdown/DropdownHandler.scala

+  document.onclick = (e: Event) => {
+    if e.target.asInstanceOf[html.Element].id != "dropdown-button" then
+      document.getElementById("dropdown-content").classList.remove("show")
+  }


Use document.addEventListener('click', (Event) => Unit) instead. onclick allows to attach only one handler per event so if anybody somewhere else did document.onclick, this handler would get overriden.

document is frequently used and it's very likely that somebody overrides it

Will change

pikinier20 · 2021-05-27T06:54:37Z

scaladoc-js/src/versions-dropdown/DropdownHandler.scala

+@JSExportTopLevel("dropdownHandler")
+def dropdownHandler() =
+  if document.getElementById("dropdown-content").getElementsByTagName("a").size > 0 &&
+     window.getSelection.toString.length == 0 then


why do you need to check for selection?

To let people copy the version without clicking the button

that's a good point. It didn't occur to me.

pikinier20 · 2021-05-27T06:59:53Z

scaladoc-js/src/versions-dropdown/DropdownHandler.scala

+  for i <- 0 until a.length do
+    val txtValue = a(i).innerText
+    val disp = if txtValue.toUpperCase.indexOf(filter) > -1 then
+      ""
+    else
+      "none"
+    a(i).asInstanceOf[html.Anchor].style.display = disp


It seems that in Scala.js you can use HTMLCollection just like Seq, so you could just do a.foreach

scala-js/scala-js-dom#194
https://github.com/scala-js/scala-js-dom/blob/master/src/main/scala/org/scalajs/dom/ext/Extensions.scala

pikinier20 · 2021-05-27T07:03:51Z

scaladoc-js/src/versions-dropdown/DropdownHandler.scala

+  for i <- 0 until a.length do
+    val txtValue = a(i).innerText
+    val disp = if txtValue.toUpperCase.indexOf(filter) > -1 then
+      ""
+    else
+      "none"
+    a(i).asInstanceOf[html.Anchor].style.display = disp


I think it's better to use css class instead of inline style

julienrf

Interesting! Do you mind adding more comments to the implementation class DropdownHandler, and also user documentation on how to use this feature? The most important thing is that we never document the expected format of the JSON document that provides the versions. An example would be welcome.

I’m curious to see how you eventually build the documentation for several versions. Did you experiment with some solutions already? It seems tempting to leave the content in the Git history, at specific tags, but then it means that to build the documentation you would have to perform multiple Git commands, and also sometimes you want to be able to keep improving the documentation even after a release. I think the other alternative would be to keep every version of the documentation in subdirectories? Then the process for creating a new version of the documentation would be to copy the current docs into a new subdirectory and update the JSON dictionary accordingly.

scaladoc/src/dotty/tools/scaladoc/ScaladocSettings.scala

julienrf · 2021-06-08T09:08:55Z

scaladoc-js/src/versions-dropdown/DropdownHandler.scala

+            window.sessionStorage.setItem(KEY, UNDEFINED_VERSIONS)
+            disableButton()
+        }
+      catch // Globals.versionDictionaruUrl is undefined


Why not check if versionsDictionaryUrl is set before calling getURLContent?

The exception is not thrown by getUrlContent but by accessing versionsDictionaryUrl itself.
When I want to access the js proprty that actually does not exists (because not always we want to have more docs linked) we do not append js property to html header properties, thus when we want to access it we get and exception at js runtime. I don't know if I can handle this one better, I did it after inspecting the transpiled js code and it's the only solution I could come up with.

Would a if Globals.versionDictionaryUrl == js.undefined work?

I will confirm that, but if I recall correctly calling Globals.versionDictionaryUrl throws the exception, not the comparison

I changed the type of versionDictionaryUrl to js.UndefOr[String] then did your comparision. As I said the exception is thrown by accessing the property at js runtime so I wrapped it with try catch

In addition to changing it to js.UndefOr[String], use

if (js.typeOf(Globals.versionDictionaryUrl) != "undefined") { // it's defined } else { // it's not }

js.typeOf is magical, like JavaScript's typeof.

Thanks, will try out

scaladoc-js/src/versions-dropdown/DropdownHandler.scala

BarkingBad · 2021-06-08T11:56:36Z

Hi @julienrf

I know I haven't provided yet any documentation, I was about to as soon as we implement it for dotty.epfl.ch docs to make sure that everything works smooth. For now I have mocked up things (will update with link after republishing snapshot). If you want to test it yourself you have to insert manually json to the session storage at key versions-json with value { "versions": { "3.0.0": "link", "3.0.1": "link2" }}

When it comes to the deploy, we provide dynamic interface for injecting dictionary of versions with url locations and it's up to user to manage the releases. User can keep them as he wish as long as they are available at their url path. For dotty, we will probably manage it with github actions by checking out git tree at provided list of tags, then getting tasty files, at last we will generate all the html docs using the newest scaladoc (for keeping the UI interface concise).

…ariable

BarkingBad · 2021-06-08T12:49:30Z

@julienrf here is documentation deployed for tests if you are interested. Ofc as I said, you have to edit sessions storage by yourself since there is no config file provided yet

BarkingBad requested review from romanowski and pikinier20 May 25, 2021 13:40

BarkingBad linked an issue May 25, 2021 that may be closed by this pull request

dotty.epfl.ch/docs should provide option to pick up a version that is documented #12524

Open

BarkingBad force-pushed the scaladoc/drop-down-revision branch 2 times, most recently from 468fe96 to c46d686 Compare May 25, 2021 14:29

pikinier20 suggested changes May 27, 2021

View reviewed changes

BarkingBad force-pushed the scaladoc/drop-down-revision branch from b396d86 to d165021 Compare May 27, 2021 12:30

romanowski approved these changes May 27, 2021

View reviewed changes

BarkingBad enabled auto-merge May 27, 2021 14:11

pikinier20 self-requested a review June 8, 2021 08:34

pikinier20 approved these changes Jun 8, 2021

View reviewed changes

julienrf reviewed Jun 8, 2021

View reviewed changes

BarkingBad added 2 commits June 8, 2021 14:07

Add browsable versions extension for scaladoc

d7bd586

Change local storage to session storage, fix bugs with undefined js v…

84feae8

…ariable

BarkingBad force-pushed the scaladoc/drop-down-revision branch from d165021 to 84feae8 Compare June 8, 2021 12:08

BarkingBad disabled auto-merge June 8, 2021 13:00

Chagne try catching of undefined scalajs property to js.typeOf

040c774

BarkingBad enabled auto-merge June 8, 2021 14:28

BarkingBad merged commit 61a6833 into scala:master Jun 8, 2021

BarkingBad deleted the scaladoc/drop-down-revision branch June 8, 2021 15:06

Kordyjan added this to the 3.0.2 milestone Aug 2, 2023

Add browsable versions extension for scaladoc #12596

Add browsable versions extension for scaladoc #12596

Uh oh!

Conversation

BarkingBad commented May 25, 2021

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

julienrf left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sjrd Jun 8, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

BarkingBad commented Jun 8, 2021

Uh oh!

BarkingBad commented Jun 8, 2021

Uh oh!

Uh oh!

sjrd Jun 8, 2021 •

edited

Loading