CRs from review

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

@@ -44,7 +44,13 @@ class HtmlRenderer(rootPackage: Member, members: Map[DRI, Member])(using ctx: Do
           Using(Files.walk(file)) { stream =>
             stream.iterator().asScala.toSeq
               .map(from => Resource.File(resourceFile.toPath.relativize(from).toString, from))
-          }.get
+          }.fold (
+            { t =>
+              report.warn(s"Error occured while processing _assets file.", t)
+              Seq.empty
+            },
+            identity
+          )
         }
       }
     val resources = staticSiteResources ++ allResources(allPages) ++ onlyRenderedResources

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

@@ -34,7 +34,6 @@ trait Locations(using ctx: DocContext):
     cache.get(dri) match
       case null =>
         val path = dri match
-          // case `docsRootDRI` => List("docs", "index")
           case `apiPageDRI` =>
             if ctx.args.apiSubdirectory && ctx.staticSiteContext.nonEmpty
               then List("api", "index")

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

@@ -74,12 +74,12 @@ abstract class Renderer(rootPackage: Member, val members: Map[DRI, Member], prot
             )
           updatedTemplates.result()
 
-        val newTemplates = updateSettings(Seq(siteContext.staticSiteRoot.rootTemplate), newSettings.to(ListBuffer))
+        val newTemplates = updateSettings(Seq(rootTemplate), newSettings.to(ListBuffer))
         val templatePages = newTemplates.map(templateToPage(_, siteContext))
 
         val newRoot = newTemplates.head
 
-        if newRoot.children.size == 0 && newRoot.templateFile.rawCode == ""
+        if newRoot.children.isEmpty && newRoot.templateFile.rawCode.isEmpty
         then rootPckPage.withTitle(args.name)
         else {
           val newRootPage = templateToPage(newRoot, siteContext)

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

@@ -8,11 +8,13 @@ import collection.JavaConverters._
 import java.util.Optional
 
 enum Sidebar:
-  case Root(index: Option[String], pages: List[Sidebar])
-  case Category(title: Option[String], indexPath: Option[String], nested: List[Sidebar], directory: Option[String])
+  case Root(index: Option[String], pages: List[Sidebar.Child])
+  case Category(title: Option[String], indexPath: Option[String], nested: List[Sidebar.Child], directory: Option[String])
   case Page(title: Option[String], pagePath: String)
 
 object Sidebar:
+
+  type Child = Category | Page
   case class RawRoot(var rootIndex: String, var pages: JList[RawInput]):
     def this() = this("", JList())
 
@@ -30,24 +32,40 @@ object Sidebar:
 
   private object RootTypeRef extends TypeReference[RawRoot]
 
-  private def toSidebar(r: RawInput): Sidebar = r match
+  private def toSidebar(r: RawInput): Sidebar.Child = r match
     case RawInput(title, page, index, subsection, dir) if page.nonEmpty && index.isEmpty && subsection.isEmpty() || title == "Blog" =>
       Sidebar.Page(Option.when(title.nonEmpty)(title), page)
     case RawInput(title, page, index, subsection, dir) if page.isEmpty && (!subsection.isEmpty() || !index.isEmpty()) =>
       Sidebar.Category(Option.when(title.nonEmpty)(title), Option.when(index.nonEmpty)(index), subsection.asScala.map(toSidebar).toList, Option.when(dir.nonEmpty)(dir))
 
-  def load(content: String): Sidebar.Root =
-    val mapper = ObjectMapper(YAMLFactory())
-    val root: RawRoot = mapper.readValue(content, RootTypeRef)
-
-    val rootIndex: String = root.rootIndex
-    val pages: List[Sidebar] = root.pages.asScala.toList.map(toSidebar)
-    Sidebar.Root(Option.when(rootIndex.nonEmpty)(rootIndex), pages)
+  private def schemaMessage: String =
+    s"""Static site YAML configuration file should comply to following model:
+      |case class Root(rootIndex: String, pages: List[Child])
+      |case class Page(title: Option[String], page: String) extends Child
+      |case class Subsection(
+      |  index: Option[String],
+      |  title: Option[String],
+      |  directory: Option[String],
+      |  subsection: List[Child]
+      |)
+      |""".stripMargin
 
-  def load(file: java.io.File): Sidebar.Root =
+  def load(content: String | java.io.File)(using CompilerContext): Sidebar.Root =
+    import scala.util.Try
     val mapper = ObjectMapper(YAMLFactory())
-    val root: RawRoot = mapper.readValue(file, RootTypeRef)
+    def readValue = content match
+      case s: String => mapper.readValue(s, RootTypeRef)
+      case f: java.io.File => mapper.readValue(f, RootTypeRef)
+
+    val root: RawRoot = Try(readValue)
+      .fold(
+        { e =>
+          report.warn(schemaMessage, e)
+          RawRoot("", java.util.Collections.emptyList())
+        },
+        identity
+      )
 
     val rootIndex: String = root.rootIndex
-    val pages: List[Sidebar] = root.pages.asScala.toList.map(toSidebar)
+    val pages: List[Sidebar.Child] = root.pages.asScala.toList.map(toSidebar)
     Sidebar.Root(Option.when(rootIndex.nonEmpty)(rootIndex), pages)

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

@@ -24,10 +24,22 @@ class StaticSiteLoader(val root: File, val args: Scaladoc.Args)(using StaticSite
       }
   }
 
+  /** Method loading static site structure based on YAML configuration file.
+   *
+   * The rendered static site will only contain pages that are present in YAML.
+   * The following rules are applied:
+   *  - Each subsection will be a separate directory.
+   *  - Nested subsections will result in nested directories.
+   *  - If the subsection object contains location of index and doesn't contain any item,
+   *    items are loaded using file system from the directory of the index file.
+   *  - By default, directory name is a subsection title converted to kebab case.
+   *    However, you can override default name by setting "directory" property of the subsection object.
+   *
+   */
   def loadBasedOnYaml(yamlRoot: Sidebar.Root): StaticSiteRoot = {
     val rootDest = ctx.docsPath.resolve("index.html").toFile
     val rootIndex = yamlRoot.index
-      .map(Paths.get(root.getPath, _).toFile)
+      .map(ctx.docsPath.resolve(_).toFile)
       .filter(_.exists)
       .fold(emptyTemplate(rootDest, "index")) { f =>
         val loaded = loadTemplateFile(f)
@@ -36,13 +48,13 @@ class StaticSiteLoader(val root: File, val args: Scaladoc.Args)(using StaticSite
         loaded
       }.copy(title = TemplateName.FilenameDefined(args.name))
 
-    def loadChild(pathFromRoot: Path): Sidebar => LoadedTemplate = {
+    def loadChild(pathFromRoot: Path): Sidebar.Child => LoadedTemplate = {
       case Sidebar.Category(optionTitle, optionIndexPath, nested, dir) =>
         val indexPageOpt = optionIndexPath
           .map(relativizeIfNeeded)
           .map(_.toFile)
           .filter(_.exists)
-          .map(loadTemplateFile)
+          .map(loadTemplateFile(_))
         val title = (
           optionTitle.map(TemplateName.SidebarDefined(_)) ++
           indexPageOpt.map(_.title)
@@ -73,15 +85,9 @@ class StaticSiteLoader(val root: File, val args: Scaladoc.Args)(using StaticSite
       case Sidebar.Page(optionTitle, pagePath) =>
         val path = relativizeIfNeeded(pagePath)
         val file = path.toFile
-        val templateFile = loadTemplateFile(file)
-        val withUpdatedTitle = optionTitle.fold(templateFile) { t => templateFile.title match
-          case _: TemplateName.FilenameDefined => templateFile.copy(title = TemplateName.SidebarDefined(t))
-          case _ => templateFile
-        }
-        LoadedTemplate(withUpdatedTitle, List.empty, pathFromRoot.resolve(file.getName).toFile)
-      case Sidebar.Root(_, _) =>
-        // Cannot happen
-        ???
+        val title = optionTitle.map(TemplateName.SidebarDefined(_))
+        val templateFile = loadTemplateFile(file, title)
+        LoadedTemplate(templateFile, List.empty, pathFromRoot.resolve(file.getName).toFile)
     }
     val rootTemplate = LoadedTemplate(rootIndex, yamlRoot.pages.map(c => loadChild(ctx.docsPath)(c)) ++ loadBlog(), rootDest)
     val mappings = createMapping(rootTemplate)

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

@@ -58,7 +58,7 @@ final val LineSeparator = "\n"
 
 def yamlParser(using ctx: StaticSiteContext): Parser = Parser.builder(defaultMarkdownOptions).build()
 
-def loadTemplateFile(file: File)(using ctx: StaticSiteContext): TemplateFile = {
+def loadTemplateFile(file: File, titleOverride: Option[TemplateName] = None)(using ctx: StaticSiteContext): TemplateFile = {
   val lines = Files.readAllLines(file.toPath).asScala.toList
 
   val (config, content) = if (lines.head == ConfigSeparator) {
@@ -105,7 +105,7 @@ def loadTemplateFile(file: File)(using ctx: StaticSiteContext): TemplateFile = {
     rawCode = content.mkString(LineSeparator),
     settings = settings,
     name = name,
-    title = stringSetting(allSettings, "title").map(TemplateName.YamlDefined(_)).getOrElse(TemplateName.FilenameDefined(name)),
+    title = stringSetting(allSettings, "title").map(TemplateName.YamlDefined(_)).orElse(titleOverride).getOrElse(TemplateName.FilenameDefined(name)),
     hasFrame = !stringSetting(allSettings, "hasFrame").contains("false"),
     resources = (listSetting(allSettings, "extraCSS") ++ listSetting(allSettings, "extraJS")).flatten.toList,
     layout = stringSetting(allSettings, "layout"),

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

@@ -115,25 +115,9 @@ case class TemplateFile(
     // Library requires mutable maps..
     val mutableProperties = new JHashMap(ctx.properties.transform((_, v) => asJavaElement(v)).asJava)
 
-    val tag = new Tag("highlight"):
-      override def render(context: TemplateContext, nodes: Array[? <: LNode]): Object =
-        super.asString(nodes(0).render(context), context) match
-          case "diff" =>
-            s"<pre><code class=\"language-diff hljs\" data-lang=\"diff\">${super.asString(nodes(1).render(context), context)}</code></pre>\n\n"
-          case _ =>
-            report.warn("Unsupported highlight value. Currenlty supported values are: `diff`", file)(using ssctx.outerCtx)
-            s"```${super.asString(nodes(1).render(context), context)}```\n\n"
-
-    val tag2 = new Tag("link"):
-      override def render(context: TemplateContext, nodes: Array[? <: LNode]): Object =
-        super.asString(nodes(0).render(context), context) match
-          case sth =>
-            report.warn(s"Unsupported link tag. Link to $sth can't be resolved", file)(using ssctx.outerCtx)
-            "/"
-
     val parseSettings = ParseSettings.Builder().withFlavor(Flavor.JEKYLL).build()
 
-    val rendered = Template.parse(this.rawCode, parseSettings).`with`(tag).`with`(tag2).render(mutableProperties)
+    val rendered = Template.parse(this.rawCode, parseSettings).render(mutableProperties)
 
     // We want to render markdown only if next template is html
     val code = if (isHtml || layoutTemplate.exists(!_.isHtml)) rendered else