Merge pull request #2608 from dotty-staging/topic/add-toc

Add include for rendering sidebar in docs

Author: felixmulder

doc-tool/resources/_includes/sidebar.html

@@ -1,7 +1,7 @@
 <div class="index-wrapper" style="top: {{ sidebarTop }};">
     <ul class="toc">
         {% assign parent = page.path | first %}
-        {% for title in sidebar %}
+        {% for title in sidebar.titles %}
         <li>{% renderTitle title, parent %}</li>
         {% endfor %}
     </ul>

doc-tool/src/dotty/tools/dottydoc/staticsite/DefaultParams.scala

@@ -43,7 +43,7 @@ case class DefaultParams(
         "root" -> site.root
       ).asJava,
 
-      "sidebar" -> sidebar.titles.asJava
+      "sidebar" -> sidebar.toMap
     )
     val entityMap = entity match {
       case NonEntity => Map.empty
@@ -79,7 +79,11 @@ case class SiteInfo(
   root: String
 )
 
-case class Sidebar(titles: List[Title])
+case class Sidebar(titles: List[Title]) {
+  import model.JavaConverters._
+  def toMap: JMap[String, _] =
+    Map("titles" -> titles.map(_.toMap).asJava).asJava
+}
 
 object Sidebar {
   def apply(map: HashMap[String, AnyRef]): Option[Sidebar] = Option(map.get("sidebar")).map {
@@ -91,7 +95,15 @@ object Sidebar {
   def empty: Sidebar = Sidebar(Nil)
 }
 
-case class Title(title: String, url: Option[String], subsection: List[Title])
+case class Title(title: String, url: Option[String], subsection: List[Title], description: Option[String]) {
+  import model.JavaConverters._
+  def toMap: JMap[String, _] = Map(
+    "title" -> title,
+    "url" -> url.getOrElse(null), // ugh, Java
+    "subsection" -> subsection.map(_.toMap).asJava,
+    "description" -> description.getOrElse(null)
+  ).asJava
+}
 
 object Title {
   def apply(map: JMap[String, AnyRef]): Option[Title] = {
@@ -101,13 +113,18 @@ object Title {
     val url = Option(map.get("url")).collect {
       case s: String => s
     }
+
+    val description = Option(map.get("description")).collect {
+      case s: String => s
+    }
+
     val subsection = Option(map.get("subsection")).collect {
       case xs: JList[JMap[String, AnyRef]] @unchecked =>
         xs.asScala.map(Title.apply).toList.flatMap(x => x)
     }.getOrElse(Nil)
 
     title.map {
-      case title: String  => Title(title, url, subsection)
+      case title: String  => Title(title, url, subsection, description)
     }
   }
 }

doc-tool/src/dotty/tools/dottydoc/staticsite/tags.scala

@@ -184,8 +184,10 @@ object tags {
 
     override def render(ctx: TemplateContext, nodes: LNode*): AnyRef =
       (nodes(0).render(ctx), nodes(1).render(ctx)) match {
-        case (t: Title, parent: String) => renderTitle(t, parent)
-        case (t: Title, _) => renderTitle(t, "./") // file is in top dir
+        case (map: JMap[String, AnyRef] @unchecked, parent: String) =>
+          Title(map).map(renderTitle(_, parent)).getOrElse(null)
+        case (map: JMap[String, AnyRef] @unchecked, _) =>
+          Title(map).map(renderTitle(_, "./")).getOrElse(null) // file is in top dir
         case _ => null
       }
   }

docs/_includes/table-of-contents.html

@@ -0,0 +1,15 @@
+<ul>
+{% for item in titles %}
+<li>
+{% if item.url %}
+<a href="{{ site.baseurl }}/{{ item.url }}">{{ item.title }}</a>
+{% else %}
+{{ item.title }}
+{% endif %}
+{% if item.subsection %}
+{% assign titles = item.subsection %}
+{% include "table-of-contents" %}
+{% endif %}
+</li>
+{% endfor %}
+</ul>

docs/docs/index.md

@@ -3,10 +3,15 @@ layout: doc-page
 title: "Dotty Documentation"
 ---
 
-Dotty is a platform to try out new language concepts and compiler technologies for Scala. 
-The focus is mainly on simplification. We remove extraneous syntax (e.g. no XML literals), 
-and try to boil down Scala’s types into a smaller set of more fundamental constructors. 
+Dotty is a platform to try out new language concepts and compiler technologies for Scala.
+The focus is mainly on simplification. We remove extraneous syntax (e.g. no XML literals),
+and try to boil down Scala’s types into a smaller set of more fundamental constructors.
 The theory behind these constructors is researched in DOT, a calculus for dependent object types.
 
 In this documentation you will find information on how to use the Dotty compiler on your machine, navigate through
 the code, setup Dotty with your favorite IDE and more!
+
+Table of Contents
+=================
+{% assign titles = sidebar.titles %}
+{% include "table-of-contents" %}

docs/sidebar.yml

@@ -1,6 +1,18 @@
 sidebar:
     - title: Blog
       url: blog/index.html
+    - title: Usage
+      subsection:
+        - title: sbt-projects
+          url: docs/usage/sbt-projects.html
+        - title: IDE support for Dotty
+          url: docs/usage/ide-support.html
+        - title: cbt-projects
+          url: docs/usage/cbt-projects.html
+        - title: Dottydoc
+          url: docs/usage/dottydoc.html
+        - title: Migrating
+          url: docs/usage/migrating.html
     - title: Reference
       subsection:
         - title: New Types
@@ -71,18 +83,6 @@ sidebar:
               url: docs/reference/dropped/limit22.html
             - title: XML literals
               url: docs/reference/dropped/xml.html
-    - title: Usage
-      subsection:
-        - title: sbt-projects
-          url: docs/usage/sbt-projects.html
-        - title: IDE support for Dotty
-          url: docs/usage/ide-support.html
-        - title: cbt-projects
-          url: docs/usage/cbt-projects.html
-        - title: Dottydoc
-          url: docs/usage/dottydoc.html
-        - title: Migrating
-          url: docs/usage/migrating.html
     - title: Contributing
       subsection:
         - title: Getting Started