Merge pull request #10426 from romanowski/scala3doc/static-page-tests

Create some basic integration tests for static sites in scala3doc

Author: abgruszecki

docs/docs/index.md

@@ -1,6 +1,5 @@
 ---
 layout: doc-page
-title: "Dotty Documentation"
 ---
 
 Dotty is the project name for technologies that are considered for inclusion in Scala 3. Scala has

project/Build.scala

@@ -1171,6 +1171,7 @@ object Build {
 
   val testcasesOutputDir = taskKey[String]("Root directory where tests classses are generated")
   val testcasesSourceRoot = taskKey[String]("Root directory where tests sources are generated")
+  val testDocumentationRoot = taskKey[String]("Root directory where tests documentation are stored")
   val generateSelfDocumentation = taskKey[Unit]("Generate example documentation")
   // Note: the two tasks below should be one, but a bug in Tasty prevents that
   val generateScala3Documentation = taskKey[Unit]("Generate documentation for dotty lib")
@@ -1544,7 +1545,9 @@ object Build {
           buildInfoKeys in Test := Seq[BuildInfoKey](
             Build.testcasesOutputDir.in(Test),
             Build.testcasesSourceRoot.in(Test),
+            Build.testDocumentationRoot,
           ),
+          testDocumentationRoot := (baseDirectory.value / "test-documentations").getAbsolutePath,
           buildInfoPackage in Test := "dotty.dokka",
           BuildInfoPlugin.buildInfoScopedSettings(Test),
           BuildInfoPlugin.buildInfoDefaultSettings,

scala3doc/src/dotty/dokka/Main.scala

@@ -78,13 +78,13 @@ case class Args(
   tastyRoots: Seq[File],
   classpath: String,
   output: File,
-  docsRoot: Option[String],
-  projectVersion: Option[String],
-  projectTitle: Option[String],
-  projectLogo: Option[String],
-  defaultSyntax: Option[Args.CommentSyntax],
-  sourceLinks: List[String],
-  revision: Option[String]
+  docsRoot: Option[String] = None,
+  projectVersion: Option[String] = None,
+  projectTitle: Option[String] = None,
+  projectLogo: Option[String] = None,
+  defaultSyntax: Option[Args.CommentSyntax] = None,
+  sourceLinks: List[String] = Nil,
+  revision: Option[String] = None
 )
 
 object Args:
@@ -121,12 +121,8 @@ enum DocConfiguration extends BaseDocConfiguration:
   * - [](package.DottyDokkaConfig) is our config for Dokka.
   */
 object Main:
-  def main(args: Array[String]): Unit =
+  def main(parsedArgs: Args): Unit =
     try
-      val rawArgs = new RawArgs
-      new CmdLineParser(rawArgs).parseArgument(args:_*)
-      val parsedArgs = rawArgs.toArgs
-
       val (files, dirs) = parsedArgs.tastyRoots.partition(_.isFile)
       val (providedTastyFiles, jars) = files.toList.map(_.getAbsolutePath).partition(_.endsWith(".tasty"))
       jars.foreach(j => if(!j.endsWith(".jar")) sys.error(s"Provided file $j is not jar not tasty file") )
@@ -147,11 +143,17 @@ object Main:
       new DokkaGenerator(new DottyDokkaConfig(config), DokkaConsoleLogger.INSTANCE).generate()
 
       println("Done")
-
-      // Sometimes jvm is hanging, so we want to be sure that we force shout down the jvm
-      sys.exit(0)
     catch
       case a: Exception =>
         a.printStackTrace()
         // Sometimes jvm is hanging, so we want to be sure that we force shout down the jvm
         sys.exit(1)
+
+  def main(args: Array[String]): Unit =
+      val rawArgs = new RawArgs
+      new CmdLineParser(rawArgs).parseArgument(args:_*)
+      main(rawArgs.toArgs)
+      // Sometimes jvm is hanging, so we want to be sure that we force shout down the jvm
+      sys.exit(0)
+
+

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

@@ -41,7 +41,7 @@ case class LoadedTemplate(templateFile: TemplateFile, children: List[LoadedTempl
 
   def resolveToHtml(ctx: StaticSiteContext): ResolvedPage =
     val posts = children.map(_.lazyTemplateProperties(ctx))
-    val site = templateFile.settings.getOrElse("site", Map.empty).asInstanceOf[Map[String, Object]]
+    def getMap(key: String) = templateFile.settings.getOrElse(key, Map.empty).asInstanceOf[Map[String, Object]]
     val sourceLinks = if !file.exists() then Nil else
       // TODO (https://github.com/lampepfl/scala3doc/issues/240): configure source root
       // toRealPath is used to turn symlinks into proper paths
@@ -50,6 +50,7 @@ case class LoadedTemplate(templateFile: TemplateFile, children: List[LoadedTempl
         ctx.sourceLinks.pathTo(actualPath, operation = "edit").map("editSource" -> _ )
 
     val updatedSettings = templateFile.settings ++ ctx.projectWideProperties +
-      ("site" -> (site + ("posts" -> posts))) + ("urls" -> sourceLinks.toMap)
+      ("site" -> (getMap("site") + ("posts" -> posts))) + ("urls" -> sourceLinks.toMap) +
+      ("page" -> (getMap("page") + ("title" -> templateFile.title)))
 
     templateFile.resolveInner(RenderingContext(updatedSettings, ctx.layouts))

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

@@ -20,7 +20,7 @@ import util.Try
 
 import scala.collection.JavaConverters._
 
-class StaticSiteContext(val root: File, sourceSets: Set[SourceSetWrapper], args: Args, val sourceLinks: SourceLinks):
+class StaticSiteContext(val root: File, sourceSets: Set[SourceSetWrapper], val args: Args, val sourceLinks: SourceLinks):
 
   var memberLinkResolver: String => Option[DRI] = _ => None
 
@@ -81,16 +81,15 @@ class StaticSiteContext(val root: File, sourceSets: Set[SourceSetWrapper], args:
         val topLevelFiles = if isBlog then Seq(from, new File(from, "_posts")) else Seq(from)
         val allFiles = topLevelFiles.filter(_.isDirectory).flatMap(_.listFiles())
         val (indexes, children) = allFiles.flatMap(loadTemplate(_)).partition(_.templateFile.isIndexPage())
-        if (indexes.size > 1)
-          // TODO (https://github.com/lampepfl/scala3doc/issues/238): provide proper error handling
-          println(s"ERROR: Multiple index pages for $from found in ${indexes.map(_.file)}")
+
         def loadIndexPage(): TemplateFile =
-          val indexFiles = from.listFiles { file =>file.getName == "index.md" || file.getName == "index.html" }
-          indexFiles.size match
-            case 0 => emptyTemplate(from, from.getName)
-            case 1 => loadTemplateFile(indexFiles.head).copy(file = from)
+          val indexFiles = from.listFiles { file => file.getName == "index.md" || file.getName == "index.html" }
+          indexes match
+            case Nil => emptyTemplate(from, from.getName)
+            case Seq(loadedTemplate) => loadedTemplate.templateFile.copy(file = from)
             case _ =>
-              val msg = s"ERROR: Multiple index pages found under ${from.toPath}"
+              // TODO (https://github.com/lampepfl/scala3doc/issues/238): provide proper error handling
+              val msg = s"ERROR: Multiple index pages for $from found in ${indexes.map(_.file)}"
               throw new java.lang.RuntimeException(msg)
 
         val templateFile = if (from.isDirectory) loadIndexPage() else loadTemplateFile(from)
@@ -101,7 +100,15 @@ class StaticSiteContext(val root: File, sourceSets: Set[SourceSetWrapper], args:
             pageSettings.flatMap(_.get("date").collect{ case s: String => s}).getOrElse("1900-01-01") // blogs without date are last
           children.sortBy(dateFrom).reverse
 
-        Some(LoadedTemplate(templateFile, processedChildren.toList, from))
+        val processedTemplate = // Set provided name as arg in page for `docs`
+          if from.getParentFile.toPath == docsPath && templateFile.isIndexPage() then
+            // TODO (https://github.com/lampepfl/scala3doc/issues/238): provide proper error handling
+            if templateFile.title != "index" then println(s"[WARN] title in $from will be overriden")
+            val projectTitle = args.projectTitle.getOrElse(args.name)
+            templateFile.copy(title = projectTitle)
+          else templateFile
+
+        Some(LoadedTemplate(processedTemplate, processedChildren.toList, from))
       catch
           case e: RuntimeException =>
             // TODO (https://github.com/lampepfl/scala3doc/issues/238): provide proper error handling

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

@@ -74,7 +74,7 @@ def loadTemplateFile(file: File): TemplateFile = {
   def getSettingValue(k: String, v: JList[String]): String | List[String] =
     if v.size == 1 then v.get(0) else v.asScala.toList
 
-  val globalKeys = Set("extraJS", "extraCSS", "layout", "hasFrame", "name")
+  val globalKeys = Set("extraJS", "extraCSS", "layout", "hasFrame", "name", "title")
   val allSettings = yamlCollector.getData.asScala.toMap.transform(getSettingValue)
   val (global, inner) = allSettings.partition((k,_) => globalKeys.contains(k))
   val settings = Map("page" -> inner)

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

@@ -103,7 +103,7 @@ class SitePagesCreator(ctx: Option[StaticSiteContext]) extends BaseStaticSitePro
     val rootContent = indexes.headOption.fold(ctx.asContent(Text(), mkDRI(extra = "root_content")).get(0))(_.getContent)
 
     val root = AContentPage(
-      input.getName,
+      ctx.args.projectTitle.getOrElse(ctx.args.name),
       (List(modifiedModuleRoot.modified("API", modifiedModuleRoot.getChildren)) ++ children).asJava,
       rootContent,
       JSet(docsDRI),

scala3doc/src/dotty/dokka/transformers/PackageHierarchyTransformer.scala

@@ -63,12 +63,9 @@ class PackageHierarchyTransformer(context: DokkaContext) extends PageTransformer
 
     val packagePagesWithTokens = packagePages.map(page => (("""\.""".r.split(page.getName)).toSeq, page))
 
-    val maxDepthElem = packagePagesWithTokens.maxBy( (tokens, page) => tokens.size )
-
-    page.modified(
-      page.getName,
+    val newPages = if packagePagesWithTokens.isEmpty then page.getChildren else
+      val maxDepthElem = packagePagesWithTokens.maxBy( (tokens, page) => tokens.size )
       (otherPages ++ buildPackageTree(maxDepthElem(0).size, packagePagesWithTokens, Seq.empty)).asJava
-    )
-
 
+    page.modified(page.getName, newPages)
   }

scala3doc/test-documentations/basic/docs/Adoc.md

@@ -0,0 +1,6 @@
+---
+title: Adoc
+---
+# Header in Adoc
+
+And a text!

scala3doc/test-documentations/basic/docs/dir/index.md

@@ -0,0 +1,6 @@
+---
+title: A directory
+---
+# {{  page.title }}
+
+And a text!