Merge pull request #27 from pikinier20/scaladoc/quick-links

Implement quick links setting

Author: fanixus96

project/Build.scala

@@ -1324,6 +1324,7 @@ object Build {
       val (dirs, files) = IO.listFiles(dir).toList.partition(_.isDirectory)
       val targetDir = (Compile / resourceManaged).value.toPath.resolve(unmanagedResources.toPath.relativize(dir.toPath)).toFile
       val bundleFile = targetDir / "bundle.css"
+      if (bundleFile.exists) bundleFile.delete()
       files.foreach(file => IO.append(bundleFile, IO.readBytes(file)))
       bundleFile :: dirs.flatMap(createBundle)
     }
@@ -1836,7 +1837,17 @@ object ScaladocConfigs {
       projectFooter,
       defaultTemplate,
       Author(true),
-      Groups(true)
+      Groups(true),
+      QuickLinks(
+        List(
+          "Download::https://www.scala-lang.org/download/",
+          "Documentation::https://docs.scala-lang.org/",
+          "Libraries::https://index.scala-lang.org",
+          "Contribute::https://www.scala-lang.org/contribute/",
+          "Blog::https://www.scala-lang.org/blog/",
+          "Community::https://www.scala-lang.org/community/"
+        )
+      )
     )
   }
 

project/ScaladocGeneration.scala

@@ -129,6 +129,10 @@ object ScaladocGeneration {
     def key: String = "-usejavacp"
   }
 
+  case class QuickLinks(value: List[String]) extends Arg[List[String]] {
+    def key: String = "-quick-links"
+  }
+
   import _root_.scala.reflect._
 
   trait GenerationConfig {

project/scripts/cmdScaladocTests

@@ -40,5 +40,6 @@ dist/target/pack/bin/scaladoc \
   -project-footer "Copyright (c) 2002-2022, LAMP/EPFL" \
   -default-template static-site-main \
   -author -groups -revision main -project-version "${DOTTY_BOOTSTRAPPED_VERSION}" \
+  "-quick-links:Download::https://www.scala-lang.org/download/,Documentation::https://docs.scala-lang.org/,Libraries::https://index.scala-lang.org,Contribute::https://www.scala-lang.org/contribute/,Blog::https://www.scala-lang.org/blog/,Community::https://www.scala-lang.org/community/" \
   out/bootstrap/scaladoc-testcases/scala-"${DOTTY_NONBOOTSTRAPPED_VERSION}"/classes > "$tmp" 2>&1 || echo "generated testcases project with scripts"
 diff -rq "$OUT1" "scaladoc/output/testcases"

scaladoc/resources/dotty_res/styles/theme/layout/header.css

@@ -54,6 +54,11 @@
   margin-left: calc(3 * var(--base-spacing));
 }
 
+.logo-container {
+  display: flex;
+  align-items: center;
+}
+
 #mobile-menu-toggle {
   display: none;
 }

scaladoc/src/dotty/tools/scaladoc/QuickLink.scala

@@ -0,0 +1,15 @@
+package dotty.tools.scaladoc
+
+case class QuickLink(text: String, url: String)
+
+object QuickLink:
+  lazy val delimiter = "::"
+  def usage: String =
+    """List of quick links that is displayed in the header of documentation.
+      |The setting accepts list of quick links in format: text::url
+      |The first `::` occurence is taken as the delimiter.""".stripMargin
+  def parse(s: String): Either[String, QuickLink] =
+    s.split(delimiter, 2).toList match
+      case text :: url :: Nil => Right(QuickLink(text, url))
+      case _ => Left(s"""Invalid syntax of quick link.
+                    |$usage""".stripMargin)

scaladoc/src/dotty/tools/scaladoc/Scaladoc.scala

@@ -49,6 +49,7 @@ object Scaladoc:
     apiSubdirectory : Boolean = false,
     scastieConfiguration: String = "",
     defaultTemplate: Option[String] = None,
+    quickLinks: List[QuickLink] = List.empty
   )
 
   def run(args: Array[String], rootContext: CompilerContext): Reporter =
@@ -180,6 +181,15 @@ object Scaladoc:
           },right => Some(right))
         }
 
+      val quickLinksParsed =
+        quickLinks.get.flatMap { s =>
+          QuickLink.parse(s) match
+            case Left(err) =>
+              report.warning(err)
+              None
+            case Right(value) => Some(value)
+        }
+
       unsupportedSettings.filter(s => s.get != s.default).foreach { s =>
         report.warning(s"Setting ${s.name} is currently not supported.")
       }
@@ -220,7 +230,8 @@ object Scaladoc:
         generateInkuire.get,
         apiSubdirectory.get,
         scastieConfiguration.get,
-        defaultTemplate.nonDefault
+        defaultTemplate.nonDefault,
+        quickLinksParsed
       )
       (Some(docArgs), newContext)
     }

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

@@ -133,6 +133,12 @@ class ScaladocSettings extends SettingGroup with AllScalaSettings:
       ""
     )
 
+  val quickLinks: Setting[List[String]] =
+    MultiStringSetting(
+      "-quick-links",
+      "quick-links",
+      "List of quick links that is displayed in the header of documentation."
+    )
 
   def scaladocSpecificSettings: Set[Setting[_]] =
-    Set(sourceLinks, legacySourceLink, syntax, revision, externalDocumentationMappings, socialLinks, skipById, skipByRegex, deprecatedSkipPackages, docRootContent, snippetCompiler, generateInkuire, scastieConfiguration)
+    Set(sourceLinks, legacySourceLink, syntax, revision, externalDocumentationMappings, socialLinks, skipById, skipByRegex, deprecatedSkipPackages, docRootContent, snippetCompiler, generateInkuire, defaultTemplate, scastieConfiguration, quickLinks)

scaladoc/src/dotty/tools/scaladoc/renderers/HtmlRenderer.scala

@@ -208,37 +208,28 @@ class HtmlRenderer(rootPackage: Member, members: Map[DRI, Member])(using ctx: Do
         )
       }
 
+    def quickLinks(mobile: Boolean = false): TagArg =
+      val className = if mobile then "mobile-menu-item" else "text-button"
+      args.quickLinks.map { quickLink =>
+        a(href := quickLink.url, cls := className)(quickLink.text)
+      }
+
     div(id := "")(
       div(id := "header", cls := "body-small")(
         div(cls := "header-container-left")(
-          projectLogoElem.toSeq,
-          darkProjectLogoElem.toSeq,
-          span(cls := "project-name h300")(args.name),
+          a(href := pathToRoot(link.dri), cls := "logo-container")(
+            projectLogoElem.toSeq,
+            darkProjectLogoElem.toSeq,
+            span(cls := "project-name h300")(args.name)
+          ),
           span(onclick := "dropdownHandler(event)", cls := "text-button with-arrow", id := "dropdown-trigger")(
             a(args.projectVersion.map(v => div(cls:="projectVersion")(v)).toSeq),
           ),
           div(id := "version-dropdown", cls := "dropdown-menu") ()
         ),
          div(cls:="header-container-right")(
-            button(id := "search-toggle", cls := "icon-button"),
-            a(href := "https://www.scala-lang.org/download/", cls := "text-button") (
-              "Download",
-            ),
-            a(href := "https://docs.scala-lang.org/", cls := "text-button") (
-              "Documentation",
-            ),
-            a(href := "https://index.scala-lang.org", cls := "text-button") (
-              "Libraries",
-            ),
-            a(href := "https://www.scala-lang.org/contribute/", cls := "text-button") (
-              "Contribute",
-            ),
-            a(href := "https://www.scala-lang.org/contribute/", cls := "text-button") (
-              "Blog",
-            ),
-            a(href := "https://www.scala-lang.org/blog/", cls := "text-button") (
-              "Community",
-            ),
+          button(id := "search-toggle", cls := "icon-button"),
+          quickLinks(),
           span(id := "theme-toggle", cls := "icon-button"),
           span(id := "mobile-menu-toggle", cls := "icon-button hamburger"),
         ),
@@ -253,24 +244,7 @@ class HtmlRenderer(rootPackage: Member, members: Map[DRI, Member])(using ctx: Do
         ),
         div(cls := "mobile-menu-container body-medium")(
           input(id := "mobile-scaladoc-searchbar-input", cls := "scaladoc-searchbar-input", `type` := "search", `placeholder`:= "Find anything"),
-          a(href := "https://www.scala-lang.org/download/", cls := "mobile-menu-item") (
-            "Download",
-          ),
-          a(href := "https://docs.scala-lang.org/", cls := "mobile-menu-item") (
-            "Documentation",
-          ),
-          a(href := "https://index.scala-lang.org", cls := "mobile-menu-item") (
-            "Libraries",
-          ),
-          a(href := "https://www.scala-lang.org/contribute/", cls := "mobile-menu-item contribute") (
-            "Contribute",
-          ),
-          a(href := "https://www.scala-lang.org/contribute/", cls := "mobile-menu-item") (
-            "Blog",
-          ),
-          a(href := "https://www.scala-lang.org/blog/", cls := "mobile-menu-item") (
-            "Community",
-          ),
+          quickLinks(mobile = true),
           span(id := "mobile-theme-toggle", cls := "mobile-menu-item mode"),
         )
       ),