Change requests: Uniformize property names in YAML config

Author: pikinier20

docs/sidebar.yml

@@ -1,6 +1,5 @@
-rootIndex: index.md
-pages:
-  # - title: Blog
+index: index.md
+subsection:
   - title: Usage
     subsection:
       - page: usage/sbt-projects.md

scaladoc-testcases/docs/sidebar.yml

@@ -1,5 +1,5 @@
-rootIndex: index.md
-pages:
+index: index.md
+subsection:
   - page: docs/f1.md
   - page: docs/f2.md
   - page: docs/f3.md

scaladoc/src/dotty/tools/scaladoc/site/SidebarParser.scala

@@ -9,24 +9,15 @@ import java.util.Optional
 import scala.beans._
 
 enum Sidebar:
-  case Root(index: Option[String], pages: List[Sidebar.Child])
   case Category(
     title: Option[String],
     indexPath: Option[String],
-    nested: List[Sidebar.Child],
+    nested: List[Sidebar],
     directory: Option[String]
   )
   case Page(title: Option[String], pagePath: String, hidden: Boolean)
 
 object Sidebar:
-
-  type Child = Category | Page
-  case class RawRoot(var rootIndex: String, var pages: JList[RawInput]):
-    def this() = this("", JList())
-
-    def setRootIndex(s: String) = rootIndex = s
-    def setPages(l: JList[RawInput]) = pages = l
-
   case class RawInput(
     @BeanProperty var title: String,
     @BeanProperty var page: String,
@@ -37,9 +28,9 @@ object Sidebar:
   ):
     def this() = this("", "", "", JList(), "", false)
 
-  private object RootTypeRef extends TypeReference[RawRoot]
+  private object RawInputTypeRef extends TypeReference[RawInput]
 
-  private def toSidebar(r: RawInput)(using CompilerContext): Sidebar.Child = r match
+  private def toSidebar(r: RawInput)(using CompilerContext): Sidebar = r match
     case RawInput(title, page, index, subsection, dir, hidden) if page.nonEmpty && index.isEmpty && subsection.isEmpty() =>
       Sidebar.Page(Option.when(title.nonEmpty)(title), page, hidden)
     case RawInput(title, page, index, subsection, dir, hidden) if page.isEmpty && (!subsection.isEmpty() || !index.isEmpty()) =>
@@ -49,43 +40,43 @@ object Sidebar:
       Sidebar.Page(None, page, hidden)
 
   private def schemaMessage: String =
-    s"""Static site YAML configuration file should comply to the following description:
-      |rootIndex: <string> # optional
-      |pages:
-      |  - <subsection> | <page>
+    s"""Static site YAML configuration file should comply with the following description:
+      |The root element of static site needs to be <subsection>
+      |`title` and `directory` properties are ignored in root subsection.
       |
       |<subsection>:
-      |  title: <string> # optional
-      |  index: <string> # optional
-      |  directory: <string> # optional
-      |  subsection: # optional
+      |  title: <string> # optional - Default value is file name. Title can be also set using front-matter.
+      |  index: <string> # optional - If not provided, default empty index template is generated.
+      |  directory: <string> # optional - By default, directory name is title name in kebab case.
+      |  subsection: # optional - If not provided, pages are loaded from the index directory
       |    - <subsection> | <page>
       |  # either index or subsection needs to be present
       |<page>:
-      |  title: <string> # optional
+      |  title: <string> # optional - Default value is file name. Title can be also set using front-matter.
       |  page: <string>
-      |  hidden: <boolean> # optional
+      |  hidden: <boolean> # optional - Default value is false.
       |
       |For more information visit:
       |https://docs.scala-lang.org/scala3/guides/scaladoc/static-site.html
       |""".stripMargin
 
-  def load(content: String | java.io.File)(using CompilerContext): Sidebar.Root =
+  def load(content: String | java.io.File)(using CompilerContext): Sidebar.Category =
     import scala.util.Try
     val mapper = ObjectMapper(YAMLFactory())
     def readValue = content match
-      case s: String => mapper.readValue(s, RootTypeRef)
-      case f: java.io.File => mapper.readValue(f, RootTypeRef)
+      case s: String => mapper.readValue(s, RawInputTypeRef)
+      case f: java.io.File => mapper.readValue(f, RawInputTypeRef)
 
-    val root: RawRoot = Try(readValue)
+    val root: RawInput = Try(readValue)
       .fold(
         { e =>
           report.warn(schemaMessage, e)
-          RawRoot("", java.util.Collections.emptyList())
+          new RawInput()
         },
         identity
       )
-
-    val rootIndex: String = root.rootIndex
-    val pages: List[Sidebar.Child] = root.pages.asScala.toList.map(toSidebar)
-    Sidebar.Root(Option.when(rootIndex.nonEmpty)(rootIndex), pages)
+    toSidebar(root) match
+      case c: Sidebar.Category => c
+      case _ =>
+        report.error(s"Root element is not a subsection.\n$schemaMessage")
+        Sidebar.Category(None, None, List.empty, None)

scaladoc/src/dotty/tools/scaladoc/site/StaticSiteLoader.scala

@@ -36,9 +36,9 @@ class StaticSiteLoader(val root: File, val args: Scaladoc.Args)(using StaticSite
    *    However, you can override default name by setting "directory" property of the subsection object.
    *
    */
-  def loadBasedOnYaml(yamlRoot: Sidebar.Root): StaticSiteRoot = {
+  def loadBasedOnYaml(yamlRoot: Sidebar.Category): StaticSiteRoot = {
     val rootDest = ctx.docsPath.resolve("index.html").toFile
-    val rootIndex = yamlRoot.index
+    val rootIndex = yamlRoot.indexPath
       .map(ctx.docsPath.resolve(_).toFile)
       .filter(_.exists)
       .fold(emptyTemplate(rootDest, "index")) { f =>
@@ -48,7 +48,7 @@ class StaticSiteLoader(val root: File, val args: Scaladoc.Args)(using StaticSite
         loaded
       }.copy(title = TemplateName.FilenameDefined(args.name))
 
-    def loadChild(pathFromRoot: Path): Sidebar.Child => LoadedTemplate = {
+    def loadChild(pathFromRoot: Path): Sidebar => LoadedTemplate = {
       case Sidebar.Category(optionTitle, optionIndexPath, nested, dir) =>
         val indexPageOpt = optionIndexPath
           .map(relativizeIfNeeded)
@@ -89,7 +89,7 @@ class StaticSiteLoader(val root: File, val args: Scaladoc.Args)(using StaticSite
         val templateFile = loadTemplateFile(file, title)
         LoadedTemplate(templateFile, List.empty, pathFromRoot.resolve(file.getName).toFile, hidden)
     }
-    val rootTemplate = LoadedTemplate(rootIndex, yamlRoot.pages.map(c => loadChild(ctx.docsPath)(c)) ++ loadBlog(), rootDest)
+    val rootTemplate = LoadedTemplate(rootIndex, yamlRoot.nested.map(c => loadChild(ctx.docsPath)(c)) ++ loadBlog(), rootDest)
     val mappings = createMapping(rootTemplate)
     StaticSiteRoot(rootTemplate, mappings)
   }

scaladoc/test/dotty/tools/scaladoc/site/SidebarParserTest.scala

@@ -7,36 +7,39 @@ import org.junit.Assert._
 // TODO add negaitve and more details tests
 class SidebarParserTest:
 
-  private val sidebar = """pages:
-    - title: My title
-      page: my-page1.md
-    - page: my-page2.md
-    - page: my-page3/subsection
-    - title: Reference
-      subsection:
-        - page: my-page3.md
-          hidden: true
-    - index: my-page4/index.md
-      subsection:
-        - page: my-page4/my-page4.md
-    - title: My subsection
-      index: my-page5/index.md
-      subsection:
-        - page: my-page5/my-page5.md
-    - subsection:
-        - page: my-page7/my-page7.md
-    - index: my-page6/index.md
-      subsection:
-        - index: my-page6/my-page6/index.md
-          subsection:
-            - page: my-page6/my-page6/my-page6.md
-  """
+  private val sidebar =
+    """index: index.md
+      |subsection:
+      |  - title: My title
+      |    page: my-page1.md
+      |  - page: my-page2.md
+      |  - page: my-page3/subsection
+      |  - title: Reference
+      |    subsection:
+      |      - page: my-page3.md
+      |        hidden: true
+      |  - index: my-page4/index.md
+      |    subsection:
+      |      - page: my-page4/my-page4.md
+      |  - title: My subsection
+      |    index: my-page5/index.md
+      |    subsection:
+      |      - page: my-page5/my-page5.md
+      |  - subsection:
+      |      - page: my-page7/my-page7.md
+      |  - index: my-page6/index.md
+      |    subsection:
+      |      - index: my-page6/my-page6/index.md
+      |        subsection:
+      |          - page: my-page6/my-page6/my-page6.md
+      """.stripMargin
 
   @Test
   def loadSidebar(): Unit = assertEquals(
-    Sidebar.Root(
+    Sidebar.Category(
       None,
-        List(
+      Some("index.md"),
+      List(
         Sidebar.Page(Some("My title"), "my-page1.md", false),
         Sidebar.Page(None, "my-page2.md", false),
         Sidebar.Page(None, "my-page3/subsection", false),
@@ -45,7 +48,8 @@ class SidebarParserTest:
         Sidebar.Category(Some("My subsection"), Some("my-page5/index.md"),  List(Sidebar.Page(None, "my-page5/my-page5.md", false)), None),
         Sidebar.Category(None, None,  List(Sidebar.Page(None, "my-page7/my-page7.md", false)), None),
         Sidebar.Category(None, Some("my-page6/index.md"),  List(Sidebar.Category(None, Some("my-page6/my-page6/index.md"),  List(Sidebar.Page(None, "my-page6/my-page6/my-page6.md", false)), None)), None),
-      )
+      ),
+      None
     ),
     Sidebar.load(sidebar)(using testContext)
   )