Consume sidebar.yaml in scala3doc

Now documentation generated by scala3doc has same layout as documentation build on http://dotty.epfl.ch/

Fix code highlighting in static pages

Author: romanowski

project/Build.scala

@@ -1481,6 +1481,7 @@ object Build {
             "com.vladsch.flexmark" % "flexmark-all" % "0.42.12",
             "nl.big-o" % "liqp" % "0.6.7",
             "args4j" % "args4j" % "2.33",
+            Dependencies.`jackson-dataformat-yaml`,
 
             "org.jetbrains.dokka" % "dokka-test-api" % dokkaVersion % "test",
             "com.novocode" % "junit-interface" % "0.11" % "test",

scala3doc/scala3-docs/_layouts/base.html

@@ -5,7 +5,6 @@
     - css/color-brewer.css
 extraJS:
     - js/jquery.min.js
-    - js/highlight.pack.js
     - js/bootstrap.min.js
 ---
 <link rel="dns-prefetch" href="//fonts.googleapis.com">
@@ -16,16 +15,3 @@
 
 
 {{ content }}
-
-<script>
-    $(document).ready(function() {
-  // Code hilighting (requires hilight.js to be loaded)
-  $('pre code').each(function(i, block) {
-    hljs.highlightBlock(block);
-  });
-  // Autoscroll to anchor
-  if (window.location.hash.length > 0) {
-    window.scrollTo(0, $(window.location.hash).offset().top - 90);
-  }
-})
-</script>

scala3doc/scala3-docs/index.html

@@ -20,7 +20,7 @@
                         </a>
                     </li>
                     <li class="nav-item">
-                        <a class="nav-link" href="{{ site.baseurl }}/blog/index.html">
+                        <a class="nav-link" href="docs/blog/index.html">
                             Blog
                         </a>
                     </li>

scala3doc/scala3-docs/sidebar.yml

@@ -0,0 +1 @@
+../../docs/sidebar.yml

scala3doc/src/dotty/dokka/site/SidebarParser.scala

@@ -0,0 +1,35 @@
+package dotty.dokka
+package site
+
+import com.fasterxml.jackson.dataformat.yaml.YAMLFactory;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.core.`type`.TypeReference;
+import collection.JavaConverters._
+import java.util.Optional
+
+enum Sidebar:
+  val title: String
+  case Category(title: String, nested: List[Sidebar])
+  case Page(title: String, url: String)
+
+object Sidebar:
+  case class RawInput(var title: String,var url: String, var subsection: JList[RawInput]):
+    def this() = this("", "", JList())
+
+    def setTitle(t: String) = this.title = t
+    def setUrl(u: String) = this.url = u
+    def setSubsection(l: JList[RawInput]) = this.subsection = l
+
+  private object RawTypeRef extends TypeReference[JMap[String, JList[RawInput]]]
+
+  private def toSidebar(r: RawInput): Sidebar = r match
+    case RawInput(title, url, list) if title.nonEmpty && url.nonEmpty && list.isEmpty() =>
+      Sidebar.Page(title, url)
+    case RawInput(title, url, list) if title.nonEmpty && url.isEmpty && !list.isEmpty() =>
+      Sidebar.Category(title, list.asScala.map(toSidebar).toList)
+
+  def load(content: String): Seq[Sidebar] =
+    val mapper = ObjectMapper(YAMLFactory())
+    val raw = mapper.readValue(content, RawTypeRef)
+
+    raw.get("sidebar").asScala.toList.map(toSidebar)

scala3doc/src/dotty/dokka/site/StaticSiteContext.scala

@@ -2,6 +2,8 @@ package dotty.dokka
 package site
 
 import java.io.File
+import java.nio.file.Files
+
 
 import org.jetbrains.dokka.base.parsers.MarkdownParser
 import org.jetbrains.dokka.base.transformers.pages.comments.DocTagToContentConverter
@@ -21,13 +23,22 @@ class StaticSiteContext(val root: File, sourceSets: Set[SourceSetWrapper]):
   def indexPage():Option[StaticPageNode] =
     val files = List(new File(root, "index.html"), new File(root, "index.md")).filter { _.exists() }
     if (files.size > 1) println(s"ERROR: Multiple root index pages found: ${files.map(_.getAbsolutePath)}") // TODO (#14): provide proper error handling
-    loadFiles(files).headOption
+    files.flatMap(loadTemplate(_, isBlog = false)).headOption.map(templateToPage)
 
   lazy val layouts: Map[String, TemplateFile] =
     val layoutRoot = new File(root, "_layouts")
     val dirs: Array[File] = Option(layoutRoot.listFiles()).getOrElse(Array())
     dirs.map { it => loadTemplateFile(it) }.map { it => it.name() -> it }.toMap
 
+  lazy val sideBarConfig =
+    val sidebarFile = root.toPath.resolve("sidebar.yml")
+    if (!Files.exists(sidebarFile)) None
+    else Some(Sidebar.load(Files.readAllLines(sidebarFile).asScala.mkString("\n")))
+
+  lazy val templates: Seq[LoadedTemplate] = sideBarConfig.fold(loadAllFiles())(_.map(loadSidebarContent))
+
+  lazy val pages = templates.map(templateToPage)
+
   private def isValidTemplate(file: File): Boolean =
     (file.isDirectory && !file.getName.startsWith("_")) ||
       file.getName.endsWith(".md") ||
@@ -38,7 +49,7 @@ class StaticSiteContext(val root: File, sourceSets: Set[SourceSetWrapper]):
     if (!isValidTemplate(from)) None else
       try
         val topLevelFiles = if isBlog then Seq(from, new File(from, "_posts")) else Seq(from)
-        val allFiles = topLevelFiles.filter(_.isDirectory).flatMap(_.listFiles()) 
+        val allFiles = topLevelFiles.filter(_.isDirectory).flatMap(_.listFiles())
         val (indexes, children) = allFiles.flatMap(loadTemplate(_)).partition(_.templateFile.isIndexPage())
         if (indexes.size > 1)
           println(s"ERROR: Multiple index pages for $from found in ${indexes.map(_.file)}") // TODO (#14): provide proper error handling
@@ -68,36 +79,38 @@ class StaticSiteContext(val root: File, sourceSets: Set[SourceSetWrapper]):
     new PropertyContainer(JMap())
   )
 
-  def loadAllFiles() = 
+  private def loadSidebarContent(entry: Sidebar): LoadedTemplate = entry match
+    case Sidebar.Page(title, url) =>
+      val isBlog = title == "Blog"
+      val path = if isBlog then "blog" else url.stripSuffix(".html") + ".md"
+      val file = root.toPath.resolve(path) // Add support for.html files!
+      val LoadedTemplate(template, children, tFile) = loadTemplate(file.toFile, isBlog).get // Add proper logging if file does not exisits
+      LoadedTemplate(template.copy(settings = template.settings + ("title" -> List(title))), children, tFile)
+    case Sidebar.Category(title, nested) =>
+      val fakeFile = new File(root, title)
+      LoadedTemplate(emptyTemplate(fakeFile), nested.map(loadSidebarContent), fakeFile)
+
+  private def loadAllFiles() =
     def dir(name: String)= List(new File(root, name)).filter(_.isDirectory)
-    loadFiles(dir("docs").flatMap(_.listFiles())) ++ loadFiles(dir("blog"), isBlog = true)
-
-  def loadFiles(files: List[File], isBlog: Boolean = false): List[StaticPageNode] =
-    val all = files.flatMap(loadTemplate(_, isBlog))
-    def flatten(it: LoadedTemplate): List[String] =
-      List(it.relativePath(root)) ++ it.children.flatMap(flatten)
+    dir("docs").flatMap(_.listFiles()).flatMap(loadTemplate(_, isBlog = false))
+      ++ dir("blog").flatMap(loadTemplate(_, isBlog = true))
 
+  def templateToPage(myTemplate: LoadedTemplate): StaticPageNode =
     def pathToDRI(path: String) = mkDRI(s"_.$path")
-
-    val driMap = all.flatMap(flatten).map(it => it -> pathToDRI(it)).toMap
-
-    def templateToPage(myTemplate: LoadedTemplate): StaticPageNode =
-      val dri = pathToDRI(myTemplate.relativePath(root))
-      val content = new PartiallyRenderedContent(
-        myTemplate.templateFile,
-        this,
-        JList(),
-        new DCI(Set(dri).asJava, ContentKind.Empty),
-        sourceSets.toDisplay,
-        JSet()
-      )
-      StaticPageNode(
-        myTemplate.templateFile,
-        myTemplate.templateFile.title(),
-        content,
-        JSet(dri),
-        JList(),
-        (myTemplate.children.map(templateToPage)).asJava
-      )
-
-    all.map(templateToPage)
+    val dri = pathToDRI(myTemplate.relativePath(root))
+    val content = new PartiallyRenderedContent(
+      myTemplate.templateFile,
+      this,
+      JList(),
+      new DCI(Set(dri).asJava, ContentKind.Empty),
+      sourceSets.toDisplay,
+      JSet()
+    )
+    StaticPageNode(
+      myTemplate.templateFile,
+      myTemplate.templateFile.title(),
+      content,
+      JSet(dri),
+      JList(),
+      (myTemplate.children.map(templateToPage)).asJava
+    )

scala3doc/src/dotty/dokka/site/processors.scala

@@ -90,7 +90,7 @@ class SitePagesCreator(ctx: Option[StaticSiteContext]) extends BaseStaticSitePro
   override def transform(input: RootPageNode, ctx: StaticSiteContext): RootPageNode =
     val (contentPage, others) = input.getChildren.asScala.toList.partition { _.isInstanceOf[ContentPage] }
     val modifiedModuleRoot = processRootPage(input, contentPage)
-    val (indexes, children) = ctx.loadAllFiles().partition(_.template.isIndexPage())
+    val (indexes, children) = ctx.pages.partition(_.template.isIndexPage())
       // TODO (#14): provide proper error handling
     if (indexes.size > 1) println("ERROR: Multiple index pages found $indexes}")
 
@@ -117,13 +117,21 @@ class RootIndexPageCreator(ctx: Option[StaticSiteContext]) extends BaseStaticSit
       val (navigations, rest) = nonContent.partition { _.isInstanceOf[NavigationPage] }
       val modifiedNavigation = navigations.map { it =>
         val root = it.asInstanceOf[NavigationPage].getRoot
-        val (api, rest) = root.getChildren.asScala.partition { _.getDri == apiPageDRI }
+        val api = root.getChildren.asScala.filter(_.getDri == apiPageDRI)
+
+        def toNavigationNode(page: StaticPageNode): NavigationNode = NavigationNode(
+            page.title(),
+            page.getDri.asScala.head,
+            root.getSourceSets,
+            page.getChildren.asScala.collect { case p: StaticPageNode => toNavigationNode(p)}.asJava
+          )
+
         new NavigationPage(
           new NavigationNode(
             input.getName,
             docsRootDRI,
             root.getSourceSets,
-            (rest ++ api).asJava
+            (ctx.pages.map(toNavigationNode) ++ api).asJava
           )
         )
       }

scala3doc/src/dotty/dokka/site/templates.scala

@@ -47,7 +47,7 @@ case class TemplateFile(
                          val file: File,
                          val isHtml: Boolean,
                          val rawCode: String,
-                         private val settings: Map[String, List[String]]
+                         val settings: Map[String, List[String]]
                        ):
 
   private def stringSetting(name: String): Option[String] =

scala3doc/test/dotty/dokka/site/StaticSiteContextTest.scala

@@ -0,0 +1,26 @@
+package dotty.dokka.site
+
+import org.junit.Test
+import org.junit.Assert._
+
+// TODO add negaitve and more details tests
+class SidebarParserTest:
+
+  private val sidebar = """sidebar:
+    - title: Blog
+      url: blog/index.html
+    - title: Reference
+      subsection:
+        - title: Overview
+          url: docs/reference/overview.html
+        - title: New Types
+          subsection:
+            - title: Intersection types
+              url: docs/reference/new-types/intersection-types.html
+            - title: Union types
+              url: docs/reference/new-types/union-types.html
+ """
+
+  @Test
+  def loadSidebar(): Unit =
+    assertEquals(2, Sidebar.load(sidebar).size)