Add configurable social links to scala3doc

Author: pikinier20

project/Build.scala

@@ -1621,6 +1621,9 @@ object Build {
               "-skip-by-regex:.+\\.impl($|\\..+) " +
               "-comment-syntax wiki -siteroot scala3doc/scala3-docs -project-logo scala3doc/scala3-docs/logo.svg " +
               "-external-mappings:.*java.*::javadoc::https://docs.oracle.com/javase/8/docs/api/ " +
+              "-social-links:github::https://github.com/lampepfl/dotty," +
+              "gitter::https://gitter.im/scala/scala," +
+              "twitter::https://twitter.com/scala_lang " +
               s"-source-links:$stdLibRoot=github://scala/scala/v${stdlibVersion(Bootstrapped)}#src/library " +
               s"-doc-root-content $docRootFile"
               ))

scala3doc-js/src/Main.scala

@@ -2,4 +2,5 @@ package dotty.dokka
 
 object Main extends App {
   Searchbar()
+  SocialLinks()
 }

scala3doc-js/src/social-links/SocialLinks.scala

@@ -0,0 +1,12 @@
+package dotty.dokka
+
+import org.scalajs.dom._
+import org.scalajs.dom.ext._
+
+class SocialLinks:
+  def addIcon(elem: html.Element) =
+    val img = document.createElement("img").asInstanceOf[html.Image]
+    img.src = s"${Globals.pathToRoot}images/${elem.getAttribute("data-icon-path")}"
+    elem.appendChild(img)
+
+  document.querySelectorAll(".social-icon").collect { case e: html.Element => e }.foreach(addIcon)

scala3doc/resources/dotty_res/images/discord-icon-black.png

@@ -613,6 +613,35 @@ footer .pull-right {
   position: relative;
 }
 
+#lhs-socials {
+  margin-left: 5%;
+  margin-right: 5%;
+}
+
+#footer-socials {
+  margin-left: 10px;
+  margin-right: 10px;
+  display: flex;
+  align-items: center;
+}
+
+.social-icon {
+  padding-right: 5px;
+  padding-left: 5px;
+}
+
+.social-icon img {
+  height: 20px;
+  width: 20px;
+}
+
+#generated-by {
+  position: absolute;
+  right: 10px;
+  display: flex;
+  align-items: center;
+}
+
 /* Large Screens */
 @media(min-width: 1100px) {
   :root {

scala3doc/resources/dotty_res/images/discord-icon-white.png

@@ -38,6 +38,7 @@ object Scala3doc:
     sourceLinks: List[String] = Nil,
     revision: Option[String] = None,
     externalMappings: List[ExternalDocLink] = Nil,
+    socialLinks: List[SocialLinks] = Nil,
     identifiersToSkip: List[String] = Nil,
     regexesToSkip: List[String] = Nil,
     rootDocPath: Option[String] = None

scala3doc/resources/dotty_res/images/github-icon-black.png

@@ -36,6 +36,11 @@ class Scala3docArgs extends SettingGroup with CommonScalaSettings:
       "Mapping between regexes matching classpath entries and external documentation. " +
         "'regex::[scaladoc|scala3doc|javadoc]::path' syntax is used")
 
+  val socialLinks: Setting[List[String]] =
+    MultiStringSetting("-social-links", "social-links",
+      "Links to social sites. '[github|twitter|gitter|discord]::link' syntax is used. " +
+        "'custom::link::icon_name' is also allowed, in this case icon must be present in 'images/'' directory.")
+
   val deprecatedSkipPackages: Setting[List[String]] =
     MultiStringSetting("-skip-packages", "packages", "Deprecated, please use `-skip-by-id` or `-skip-by-regex`")
 
@@ -49,7 +54,7 @@ class Scala3docArgs extends SettingGroup with CommonScalaSettings:
     StringSetting("-doc-root-content", "path", "The file from which the root package documentation should be imported.", "")
 
   def scala3docSpecificSettings: Set[Setting[_]] =
-    Set(sourceLinks, syntax, revision, externalDocumentationMappings, skipById, skipByRegex, deprecatedSkipPackages, docRootContent)
+    Set(sourceLinks, syntax, revision, externalDocumentationMappings, socialLinks, skipById, skipByRegex, deprecatedSkipPackages, docRootContent)
 
 object Scala3docArgs:
   def extract(args: List[String], rootCtx: CompilerContext):(Scala3doc.Args, CompilerContext) =
@@ -119,6 +124,14 @@ object Scala3docArgs:
         )
       )
 
+    val socialLinksParsed =
+      socialLinks.get.flatMap { s =>
+        SocialLinks.parse(s).fold(left => {
+          report.warning(left)
+          None
+        },right => Some(right))
+      }
+
     unsupportedSettings.filter(s => s.get != s.default).foreach { s =>
       report.warning(s"Setting ${s.name} is currently not supported.")
     }
@@ -142,6 +155,7 @@ object Scala3docArgs:
       sourceLinks.get,
       revision.nonDefault,
       externalMappings,
+      socialLinksParsed,
       skipById.get ++ deprecatedSkipPackages.get,
       skipByRegex.get,
       docRootContent.nonDefault

scala3doc/resources/dotty_res/images/github-icon-white.png

@@ -0,0 +1,26 @@
+package dotty.dokka
+
+import java.nio.file.Path
+import java.nio.file.Paths
+import dotty.dokka.model.api._
+import dotty.tools.dotc.core.Contexts.Context
+
+enum SocialLinks(val url: String, val whiteIconName: String, val blackIconName: String):
+  case Github(ghUrl: String) extends SocialLinks(ghUrl, "github-icon-white.png", "github-icon-black.png")
+  case Twitter(tUrl: String) extends SocialLinks(tUrl, "twitter-icon-white.png", "twitter-icon-black.png")
+  case Gitter(gUrl: String) extends SocialLinks(gUrl, "gitter-icon-white.png", "gitter-icon-black.png")
+  case Discord(dUrl: String) extends SocialLinks(dUrl, "discord-icon-white.png", "discord-icon-black.png")
+  case Custom(cUrl: String, cWhiteIconName: String, cBlackIconName: String) extends SocialLinks(cUrl, cWhiteIconName, cBlackIconName)
+
+object SocialLinks:
+  def parse(s: String): Either[String, SocialLinks] =
+    val splitted = s.split("::")
+    if splitted.size < 2 then Left(s"Social links arg $s is invalid.") else
+      splitted.head match {
+        case "github" => Right(Github(splitted(1)))
+        case "twitter" => Right(Twitter(splitted(1)))
+        case "gitter" => Right(Gitter(splitted(1)))
+        case "discord" => Right(Discord(splitted(1)))
+        case "custom" if splitted.size == 4 => Right(Custom(splitted(1), splitted(2), splitted(3)))
+        case _ => Left(s"Social links arg $s is invalid.")
+      }

scala3doc/resources/dotty_res/images/gitter-icon-black.png

@@ -164,6 +164,16 @@ class HtmlRenderer(rootPackage: Member, val members: Map[DRI, Member])(using ctx
           )
     renderNested(navigablePage)._2
 
+  private def hasSocialLinks = !args.socialLinks.isEmpty
+
+  private def socialLinks(whiteIcon: Boolean = true, additionalClass: String = "") =
+    val icon = (link: SocialLinks) => if whiteIcon then link.whiteIconName else link.blackIconName
+    args.socialLinks.map { link =>
+      a(href := link.url)(
+        span(cls := s"social-icon $additionalClass", Attr("data-icon-path") := icon(link))
+      )
+    }
+
   private def mkFrame(link: Link, parents: Vector[Link], content: => AppliedTag): AppliedTag =
     val projectLogo =
       args.projectLogo.map { path =>
@@ -187,6 +197,9 @@ class HtmlRenderer(rootPackage: Member, val members: Map[DRI, Member])(using ctx
           ),
           span(
             args.projectVersion.map(v => div(cls:="projectVersion")(v)).toList
+          ),
+          div(id := "lhs-socials")(
+            socialLinks(additionalClass = "lhs-social")
           )
         ),
         div(id := "paneSearch"),
@@ -212,12 +225,18 @@ class HtmlRenderer(rootPackage: Member, val members: Map[DRI, Member])(using ctx
               raw(" Back to top")
             )
           ),
-          raw("Generated by "),
-          a(href := "https://github.com/lampepfl/dotty/tree/master/scala3doc")(
-            img(
-              src := resolveRoot(link.dri, "images/scala3doc_logo.svg"),
-              alt := "Scala3doc",
-              cls := "scala3doc_logo"
+          div(id := "footer-socials")(
+            if hasSocialLinks then Seq(raw("Social links ")) else Nil,
+            socialLinks(whiteIcon = false, additionalClass = "footer-social")
+          ),
+          div(id := "generated-by")(
+            raw("Generated by "),
+            a(href := "https://github.com/lampepfl/dotty/tree/master/scala3doc")(
+              img(
+                src := resolveRoot(link.dri, "images/scala3doc_logo.svg"),
+                alt := "Scala3doc",
+                cls := "scala3doc_logo"
+              )
             )
           )
         )

scala3doc/resources/dotty_res/images/gitter-icon-white.png

@@ -128,6 +128,14 @@ trait Resources(using ctx: DocContext) extends Locations, Writer:
     dottyRes("fonts/dotty-icons.woff"),
     dottyRes("fonts/dotty-icons.ttf"),
     dottyRes("images/scala3doc_logo.svg"),
+    dottyRes("images/github-icon-black.png"),
+    dottyRes("images/github-icon-white.png"),
+    dottyRes("images/discord-icon-black.png"),
+    dottyRes("images/discord-icon-white.png"),
+    dottyRes("images/twitter-icon-black.png"),
+    dottyRes("images/twitter-icon-white.png"),
+    dottyRes("images/gitter-icon-black.png"),
+    dottyRes("images/gitter-icon-white.png"),
     searchData(pages)
   )