Scaladoc features parity with old scaladoc/docs.scala-lang (#13954)

* POC * Walk in order and collect previous/next * Add `Edit on Github` button and `Contriubuted` sections * Polish gathering the contributors. CSSes fixes. * Fix tooltipping snippets * Fix handling relative links for static site * Add redirects mechanism for scaladoc * Fix leftover * Fix tests * Fix gathering index html for sections without explicit index * Apply requested changes to scaladoc * Decouple Scala.js jses. Move contributors to be independent asset/ * Add support for multiple redirects * Apply requested changes. Add static site for testcases. Fix minor bugs in scaladoc. * Fix tests
scala · Nov 30, 2021 · f6b6e50 · f6b6e50
1 parent 51828cc
commit f6b6e50
Show file tree

Hide file tree

Showing 65 changed files with 718 additions and 177 deletions.
diff --git a/.github/workflows/scaladoc.yaml b/.github/workflows/scaladoc.yaml
@@ -36,7 +36,7 @@ jobs:
           java-version: 11
 
       - name: Compile and test scala3doc-js
-        run: ./project/scripts/sbt scaladoc-js/test
+        run: ./project/scripts/sbt scaladoc-js-main/test
 
       - name: Compile and test
         run: |

diff --git a/build.sbt b/build.sbt
@@ -20,7 +20,10 @@ val `tasty-core-bootstrapped` = Build.`tasty-core-bootstrapped`
 val `tasty-core-scala2` = Build.`tasty-core-scala2`
 val scaladoc = Build.scaladoc
 val `scaladoc-testcases` = Build.`scaladoc-testcases`
-val `scaladoc-js` = Build.`scaladoc-js`
+val `scaladoc-js-common` = Build.`scaladoc-js-common`
+val `scaladoc-js-main` = Build.`scaladoc-js-main`
+val `scaladoc-js-markdown` = Build.`scaladoc-js-markdown`
+val `scaladoc-js-contributors` = Build.`scaladoc-js-contributors`
 val `scala3-bench-run` = Build.`scala3-bench-run`
 val dist = Build.dist
 val `community-build` = Build.`community-build`

diff --git a/docs/_layouts/blog-page.html b/docs/_layouts/blog-page.html
@@ -1,7 +1,7 @@
 ---
-layout: main
+layout: static-site-main
 ---
-<main class="container">
+<main>
     <header>
         <h1>{{ page.title }}</h1>
         <div class="byline">

diff --git a/docs/_layouts/doc-page.html b/docs/_layouts/doc-page.html
@@ -1,9 +1,22 @@
 ---
-layout: main
+layout: static-site-main
 ---
-<main class="container">
-    <header>
-        <h1>{{ page.title }}</h1>
-    </header>
-    {{ content }}
+<main>
+  <header>
+    <h1>{{ page.title }}</h1>
+    {% if urls.editSource %}
+    <div class="byline">
+      <a href="{{ urls.editSource }}">
+        <i class="far fa-edit"></i>
+        Edit this page on GitHub
+      </a>
+    </div>
+    {% endif %}
+  </header>
+  {{ content }}
+  <div class="content-contributors hidden">
+    <h5>Contributors to this page:</h5>
+    <div id="documentation-contributors" class="contributors-container"></div>
+  </div>
 </main>
+
diff --git a/docs/_layouts/main.html b/docs/_layouts/main.html
@@ -1,13 +1,12 @@
 ---
 layout: base
+extraJS:
+  - js/contributors.js
+extraCSS:
+  - css/content-contributors.css
 ---
 <div id="content-wrapper">
-    {% if page.movedTo %}
-    <aside class="warning">
-      The content of this page is outdated. Click <a href="{{ page.movedTo }}">here</a> to find the up to date version of this page.
-    </aside>
-    {% endif %}
-    {{ content }}
+  {{ content }}
 </div>
 <script>
   ((window.gitter = {}).chat = {}).options = {

diff --git a/docs/_layouts/redirect.html b/docs/_layouts/redirect.html
@@ -0,0 +1,14 @@
+---
+hasFrame: false
+---
+<!DOCTYPE html>
+<html lang="en-US">
+  <meta charset="utf-8">
+  <title>Redirecting&hellip;</title>
+  <link rel="canonical" href="{{ redirectTo }}">
+  <script>location="{{ redirectTo }}"</script>
+  <meta http-equiv="refresh" content="0; url={{ redirectTo }}">
+  <meta name="robots" content="noindex">
+  <h1>Redirecting&hellip;</h1>
+  <a href="{{ redirectTo }}">Click here if you were not redirected.</a>
+</html>
diff --git a/docs/_layouts/static-site-main.html b/docs/_layouts/static-site-main.html
@@ -0,0 +1,49 @@
+---
+layout: main
+---
+<div class="container">
+  <div id="site-header">
+    <div class="wrap">
+      <nav class="navigation" role="menu">
+        <ul class="navigation-menu">
+          <li class="navigation-menu-item">
+            <a href="https://docs.scala-lang.org/" class="active">Documentation</a>
+          </li>
+          <li class="navigation-menu-item">
+            <a href="https://www.scala-lang.org/download/">Download</a>
+          </li>
+          <li class="navigation-menu-item">
+            <a href="https://www.scala-lang.org/community/">Community</a>
+          </li>
+          <li class="navigation-menu-item">
+            <a href="https://index.scala-lang.org">Libraries</a>
+          </li>
+          <li class="navigation-menu-item">
+            <a href="https://www.scala-lang.org/contribute/">Contribute</a>
+          </li>
+          <li class="navigation-menu-item">
+            <a href="https://www.scala-lang.org/blog/">Blog</a>
+          </li>
+        </ul>
+      </nav>
+    </div>
+  </div>
+  {% if page.movedTo %}
+  <aside class="warning">
+    The content of this page is outdated. Click <a href="{{ page.movedTo }}">here</a> to find the up to date version of this page.
+  </aside>
+  {% endif %}
+  {{ content }}
+  <nav class="arrows-wrapper" aria-label="Page navigation">
+    {% if page.previous %}
+    <a rel="prev" href="{{ page.previous }}" class="arrows previous" aria-keyshortcuts="Left">
+        <i class="fa fa-angle-left"></i>
+    </a>
+    {% endif %}
+    {% if page.next %}
+    <a rel="next" href="{{ page.next }}" class="arrows next" aria-keyshortcuts="Right">
+        <i class="fa fa-angle-right"></i>
+    </a>
+    {% endif %}
+  </nav>
+</div>
diff --git a/docs/blog/index.html b/docs/blog/index.html
@@ -1,5 +1,5 @@
 ---
-layout: main
+layout: static-site-main
 title: Blog
 ---
 <main class="container">

diff --git a/docs/css/dottydoc.css b/docs/css/dottydoc.css
@@ -25,6 +25,10 @@ main > h1 {
   margin-bottom: 20px;
 }
 
+.byline {
+  font-size: 14px;
+}
+
 .byline, .byline a {
   color: grey;
 }
@@ -265,4 +269,4 @@ aside.success {
 header {
   position: static !important;
   width: 100% !important;
-}
+}
diff --git a/docs/docs/reference/experimental/named-typeargs.md b/docs/docs/reference/experimental/named-typeargs.md
@@ -2,6 +2,7 @@
 layout: singlepage-overview
 scala3: true
 title: "Named Type Arguments"
+redirectFrom: reference/other-new-features/named-typeargs.html
 ---
 
 **Note:** This feature is implemented in Scala 3, but is not expected to be part of Scala 3.0.

diff --git a/docs/docs/reference/other-new-features/named-typeargs.md b/docs/docs/reference/other-new-features/named-typeargs.md
diff --git a/project/Build.scala b/project/Build.scala
@@ -340,7 +340,8 @@ object Build {
       "-skip-by-id:scala.runtime.MatchCase",
       "-project-footer", s"Copyright (c) 2002-$currentYear, LAMP/EPFL",
       "-author",
-      "-groups"
+      "-groups",
+      "-default-template", "static-site-main"
     ) ++ extMap
   }
 
@@ -1255,16 +1256,43 @@ object Build {
   lazy val `scaladoc-testcases` = project.in(file("scaladoc-testcases")).
     dependsOn(`scala3-compiler-bootstrapped`).
     settings(commonBootstrappedSettings)
-  lazy val `scaladoc-js` = project.in(file("scaladoc-js")).
+
+
+  /**
+   * Collection of projects building targets for scaladoc, these are:
+   * - common - common module for javascript shared among html and markdown outpu
+   * - main - main target for default scaladoc producing html webpage
+   * - markdown - companion js for preprocessing features. Can be later used with some templating engine
+   * - contributors - not related project to any of forementioned modules. Used for presenting contributors for static site.
+   *                   Made as an indepented project to be scaladoc-agnostic.
+   */
+  lazy val `scaladoc-js-common` = project.in(file("scaladoc-js/common")).
+    enablePlugins(DottyJSPlugin).
+    dependsOn(`scala3-library-bootstrappedJS`).
+    settings(libraryDependencies += ("org.scala-js" %%% "scalajs-dom" % "1.1.0").cross(CrossVersion.for3Use2_13))
+
+  lazy val `scaladoc-js-main` = project.in(file("scaladoc-js/main")).
+    enablePlugins(DottyJSPlugin).
+    dependsOn(`scaladoc-js-common`).
+    settings(
+      scalaJSUseMainModuleInitializer := true,
+      Test / fork := false
+    )
+
+  lazy val `scaladoc-js-markdown` = project.in(file("scaladoc-js/markdown")).
+    enablePlugins(DottyJSPlugin).
+    dependsOn(`scaladoc-js-common`).
+    settings(
+      scalaJSUseMainModuleInitializer := true,
+      Test / fork := false
+    )
+
+  lazy val `scaladoc-js-contributors` = project.in(file("scaladoc-js/contributors")).
     enablePlugins(DottyJSPlugin).
     dependsOn(`scala3-library-bootstrappedJS`).
     settings(
-      Compile / scalaJSMainModuleInitializer := (sys.env.get("scaladoc.projectFormat") match {
-        case Some("md") => Some(ModuleInitializer.mainMethod("dotty.tools.scaladoc.Main", "markdownMain"))
-        case _ => Some(ModuleInitializer.mainMethod("dotty.tools.scaladoc.Main", "main"))
-      }),
       Test / fork := false,
-      Compile / scalaJSUseMainModuleInitializer := true,
+      scalaJSUseMainModuleInitializer := true,
       libraryDependencies += ("org.scala-js" %%% "scalajs-dom" % "1.1.0").cross(CrossVersion.for3Use2_13)
     )
 
@@ -1294,6 +1322,7 @@ object Build {
         name,
         scalaSrcLink(stdLibVersion, srcManaged(dottyNonBootstrappedVersion, "scala") + "="),
         dottySrcLink(referenceVersion, srcManaged(dottyNonBootstrappedVersion, "dotty") + "=", "#library/src"),
+        dottySrcLink(referenceVersion, "docs-for-dotty-page=", "#docs"),
         dottySrcLink(referenceVersion),
         "-Ygenerate-inkuire",
       ) ++ scalacOptionsDocSettings(includeExternalMappings) ++ revision ++ params ++ targets
@@ -1318,54 +1347,13 @@ object Build {
     ).
     settings(
       Compile / resourceGenerators += Def.task {
-        val jsDestinationFile = (Compile / resourceManaged).value / "dotty_res" / "scripts" / "scaladoc-scalajs.js"
-        sbt.IO.copyFile((`scaladoc-js` / Compile / fullOptJS).value.data, jsDestinationFile)
-        Seq(jsDestinationFile)
-      }.taskValue,
-      Compile / resourceGenerators += Def.task {
-        Seq("code-snippets.css", "searchbar.css", "social-links.css", "ux.css", "versions-dropdown.css").map { file =>
-          val cssDesitnationFile = (Compile / resourceManaged).value / "dotty_res" / "styles" / file
-          val cssSourceFile = (`scaladoc-js` / Compile / resourceDirectory).value / file
-          sbt.IO.copyFile(cssSourceFile, cssDesitnationFile)
-          cssDesitnationFile
-        }
-      }.taskValue,
-      Compile / resourceGenerators += Def.task {
-        import _root_.scala.sys.process._
-        import _root_.scala.concurrent._
-        import _root_.scala.concurrent.duration.Duration
-        import ExecutionContext.Implicits.global
-        val inkuireVersion = "1.0.0-M3"
-        val inkuireLink = s"https://github.com/VirtusLab/Inkuire/releases/download/$inkuireVersion/inkuire.js"
-        val inkuireDestinationFile = (Compile / resourceManaged).value / "dotty_res" / "scripts" / "inkuire.js"
-        sbt.IO.touch(inkuireDestinationFile)
-
-        def tryFetch(retries: Int, timeout: Duration): Unit = {
-          val downloadProcess = (new java.net.URL(inkuireLink) #> inkuireDestinationFile).run()
-          val result: Future[Int] = Future(blocking(downloadProcess.exitValue()))
-          try {
-            Await.result(result, timeout) match {
-              case 0 =>
-              case res if retries > 0 =>
-                println(s"Failed to fetch inkuire.js from $inkuireLink: Error code $res. $retries retries left")
-                tryFetch(retries - 1, timeout)
-              case res => throw new MessageOnlyException(s"Failed to fetch inkuire.js from $inkuireLink: Error code $res")
-            }
-          } catch {
-            case e: TimeoutException =>
-              downloadProcess.destroy()
-              if (retries > 0) {
-                println(s"Failed to fetch inkuire.js from $inkuireLink: Download timeout. $retries retries left")
-                tryFetch(retries - 1, timeout)
-              }
-              else {
-                throw new MessageOnlyException(s"Failed to fetch inkuire.js from $inkuireLink: Download timeout")
-              }
-          }
-        }
-
-        tryFetch(5, Duration(60, "s"))
-        Seq(inkuireDestinationFile)
+        DocumentationWebsite.generateStaticAssets(
+          (`scaladoc-js-contributors` / Compile / fullOptJS).value.data,
+          (`scaladoc-js-main` / Compile / fullOptJS).value.data,
+          (`scaladoc-js-contributors` / Compile / baseDirectory).value / "css",
+          (`scaladoc-js-common` / Compile / baseDirectory).value / "css",
+          (Compile / resourceManaged).value,
+        )
       }.taskValue,
       libraryDependencies ++= Dependencies.flexmarkDeps ++ Seq(
         "nl.big-o" % "liqp" % "0.6.8",
@@ -1456,10 +1444,10 @@ object Build {
           case _ => throw new IllegalArgumentException("No js destination provided")
         }
         val jsDestinationFile: File = Paths.get(destJS).toFile
-        sbt.IO.copyFile((`scaladoc-js` / Compile / fullOptJS).value.data, jsDestinationFile)
+        sbt.IO.copyFile((`scaladoc-js-markdown` / Compile / fullOptJS).value.data, jsDestinationFile)
         csses.map { file =>
           val cssDesitnationFile = Paths.get(destCSS).toFile / file
-          val cssSourceFile = (`scaladoc-js` / Compile / resourceDirectory).value / file
+          val cssSourceFile = (`scaladoc-js-markdown` / Compile / resourceDirectory).value / file
           sbt.IO.copyFile(cssSourceFile, cssDesitnationFile)
           cssDesitnationFile
         }