When using multiple roots, enumerate them in config (#336)

When using multiple roots, enumerate them in config

core/src/main/scala/com/lightbend/paradox/ParadoxProcessor.scala

@@ -49,7 +49,7 @@ class ParadoxProcessor(reader: Reader = new Reader, writer: Writer = new Writer)
     navDepth:           Int,
     navExpandDepth:     Option[Int],
     navIncludeHeaders:  Boolean,
-    expectedRoots:      Int,
+    expectedRoots:      List[String],
     pageTemplate:       PageTemplate,
     errorListener:      STErrorListener): Seq[(File, String)] = {
     require(!groups.values.flatten.map(_.toLowerCase).groupBy(identity).values.exists(_.size > 1), "Group names may not overlap")
@@ -77,11 +77,13 @@ class ParadoxProcessor(reader: Reader = new Reader, writer: Writer = new Writer)
       case None => rendered
     }
 
-    if (expectedRoots != roots.size)
+    if (expectedRoots.sorted != roots.map(_.label.path).sorted)
       throw new IllegalStateException(
-        s"Found [${roots.size}] top-level pages (pages that do no have a parent in the Table of Contents), but expected [$expectedRoots].\n" +
-        s"If this is intentional, update the `paradoxExpectedNumberOfRoots` sbt setting to reflect the new expected number of roots.\n" +
-        "Current ToC roots: " + roots.map(_.label.path).mkString("[", ", ", "]"))
+        s"Unexpected top-level pages (pages that do no have a parent in the Table of Contents).\n" +
+          s"If this is intentional, update the `paradoxRoots` sbt setting to reflect the new expected roots.\n" +
+          "Current ToC roots: " + roots.map(_.label.path).sorted.mkString("[", ", ", "]" + "\n") +
+          "Specified ToC roots: " + expectedRoots.sorted.mkString("[", ", ", "]" + "\n")
+      )
 
     outputDirectory.mkdirs()
     createMetadata(outputDirectory, properties) :: (roots flatMap { root => render(Some(root.location)) })

plugin/src/main/scala/com/lightbend/paradox/sbt/ParadoxKeys.scala

@@ -27,7 +27,9 @@ trait ParadoxKeys {
   val paradoxNavigationDepth = settingKey[Int]("Determines depth of TOC for page navigation.")
   val paradoxNavigationExpandDepth = settingKey[Option[Int]]("Depth of auto-expanding navigation below the active page.")
   val paradoxNavigationIncludeHeaders = settingKey[Boolean]("Whether to include headers in the navigation.")
+  @deprecated("Enumerate the roots in `paradoxRoots`", since = "0.6.1")
   val paradoxExpectedNumberOfRoots = settingKey[Int]("How many ToC roots to expect.")
+  val paradoxRoots = settingKey[List[String]]("Which ToC roots (pages without parent) to expect.")
   val paradoxLeadingBreadcrumbs = settingKey[List[(String, String)]]("Any leading breadcrumbs (label -> url)")
   val paradoxOrganization = settingKey[String]("Paradox dependency organization (for theme dependencies).")
   val paradoxDirectives = taskKey[Seq[Writer.Context => Directive]]("Enabled paradox directives.")

plugin/src/main/scala/com/lightbend/paradox/sbt/ParadoxPlugin.scala

@@ -50,6 +50,7 @@ object ParadoxPlugin extends AutoPlugin {
     paradoxNavigationExpandDepth := None,
     paradoxNavigationIncludeHeaders := false,
     paradoxExpectedNumberOfRoots := 1,
+    paradoxRoots := List("index.html"),
     paradoxDirectives := Writer.defaultDirectives,
     paradoxProperties := Map.empty,
     paradoxTheme := Some(builtinParadoxTheme("generic")),
@@ -166,7 +167,7 @@ object ParadoxPlugin extends AutoPlugin {
           paradoxNavigationDepth.value,
           paradoxNavigationExpandDepth.value,
           paradoxNavigationIncludeHeaders.value,
-          paradoxExpectedNumberOfRoots.value,
+          paradoxRoots.value,
           paradoxTemplate.value,
           new PageTemplate.ErrorLogger(s => strms.log.error(s))
         )

plugin/src/sbt-test/paradox/custom-directive/build.sbt

@@ -5,5 +5,6 @@ lazy val docs = project
     name := "Paradox Directives Test",
     paradoxTheme := None,
     paradoxDirectives += CustomDirective,
-    paradoxProperties += "custom.content" -> "directive"
+    paradoxProperties += "custom.content" -> "directive",
+    paradoxRoots := List("test.html"),
   )

plugin/src/sbt-test/paradox/default-theme/build.sbt

@@ -4,5 +4,5 @@ lazy val docs = project
   .settings(
     name := "Paradox Default Theme Test",
     paradoxProperties += ("canonical.base_url" -> "https://example.com/doc/"),
-    paradoxExpectedNumberOfRoots := 2,
+    paradoxRoots := List("index.html", "sub/unindexed.html"),
   )

plugin/src/sbt-test/paradox/docs-overlay/build.sbt

@@ -10,6 +10,18 @@ lazy val docs = (project in file(".")).
     // paradoxOverlayDirectories := Seq(baseDirectory.value / "src" / "commonFirst"),
     paradoxOverlayDirectories in DocsFirst := Seq(baseDirectory.value / "src" / "commonFirst"),
     paradoxOverlayDirectories in DocsSecond := Seq(baseDirectory.value / "src" / "commonFirst", baseDirectory.value / "src" / "commonSecond"),
-    paradoxExpectedNumberOfRoots in DocsFirst := 4,
-    paradoxExpectedNumberOfRoots in DocsSecond := 6,
+    paradoxRoots in DocsFirst := List(
+      "commonFirst.html",
+      "commonFirstDir/commonFirstFile.html",
+      "docsFirstDir/docsFirstSubfile.html",
+      "docsFirstFile.html",
+    ),
+    paradoxRoots in DocsSecond := List(
+      "commonFirst.html",
+      "commonFirstDir/commonFirstFile.html",
+      "commonSecond.html",
+      "commonSecondDir/commonSecondFile.html",
+      "docsSecondDir/docsSecondSubfile.html",
+      "docsSecondFile.html",
+    ),
   )

plugin/src/sbt-test/paradox/github-link/docs/expected/absolute.html → plugin/src/sbt-test/paradox/github-link/docs/expected/index.html

@@ -1 +1 @@
-https://github.com/lightbend/paradox/tree/develop/docs/src/main/paradox/absolute.md
+https://github.com/lightbend/paradox/tree/develop/docs/src/main/paradox/index.md

plugin/src/sbt-test/paradox/github-link/test

@@ -1,3 +1,3 @@
 > paradox
 
-$ must-mirror docs/target/paradox/site/main/absolute.html docs/expected/absolute.html
+$ must-mirror docs/target/paradox/site/main/index.html docs/expected/index.html

plugin/src/sbt-test/paradox/github/build.sbt

@@ -10,6 +10,7 @@ lazy val docs = (project in file("docs")).
   enablePlugins(ParadoxPlugin).
   settings(
     paradoxTheme := None,
+    paradoxRoots := List("github.html"),
 
     scmInfoTree := Some(ScmInfo(url("https://github.com/lightbend/paradox/tree/v0.2.1"), "[email protected]:lightbend/paradox.git")),
     scmInfoProject := Some(ScmInfo(url("https://github.com/lightbend/paradox"), "[email protected]:lightbend/paradox.git")),

plugin/src/sbt-test/paradox/parameterized-links/build.sbt

@@ -15,7 +15,13 @@ paradoxProperties in Compile ++= Map(
   "javadoc.akka.base_url" -> s"http://doc.akka.io/japi/akka/$akkaVersion",
   "javadoc.akka.http.base_url" -> s"http://doc.akka.io/japi/akka-http/$akkaHttpVersion"
 )
-paradoxExpectedNumberOfRoots := 5
+paradoxRoots := List(
+  "extref.html",
+  "github.html",
+  "javadoc.html",
+  "javadoc-javalib.html",
+  "scaladoc.html",
+)
 
 apiURL := Some(url(s"https://example.org/api/${version.value}"))
 scmInfo := Some(ScmInfo(url("https://github.com/lightbend/paradox"), "[email protected]:lightbend/paradox.git"))

plugin/src/sbt-test/paradox/scaladoc-2.12/build.sbt

@@ -10,3 +10,4 @@ paradoxProperties in Compile ++= Map(
   "scaladoc.akka.base_url" -> s"http://doc.akka.io/api/akka/$akkaVersion",
   "scaladoc.akka.http.base_url" -> s"http://doc.akka.io/api/akka-http/$akkaHttpVersion"
 )
+paradoxRoots := List("scaladoc-2.12.html")

plugin/src/sbt-test/paradox/site/build.sbt

@@ -5,5 +5,6 @@ lazy val docs = project
     version := "0.1-SNAPSHOT",
     name := "Paradox Test",
     paradoxLeadingBreadcrumbs := List("Alphabet" -> "https://abc.xyz/", "Google" -> "https://www.google.com"),
-    paradoxTheme := None
+    paradoxTheme := None,
+    paradoxRoots := List("a.html"),
   )

plugin/src/sbt-test/paradox/snippet-absolute/build.sbt

@@ -4,5 +4,6 @@ lazy val root = (project in file("."))
 lazy val docs = (project in file("docs"))
   .enablePlugins(ParadoxPlugin)
   .settings(
-    paradoxTheme := None
+    paradoxTheme := None,
+    paradoxRoots := List("absolute.html"),
   )

plugin/src/sbt-test/paradox/snippets/build.sbt

@@ -5,5 +5,13 @@ lazy val docs = (project in file(".")).
     paradoxProperties in Compile ++= Map(
       "snip.test.base_dir" -> (sourceDirectory in Test).value.toString,
       "snip.test-scala.base_dir" -> "../../test/scala"),
-    paradoxExpectedNumberOfRoots := 7,
+    paradoxRoots := List(
+      "configured-bases.html",
+      "group.html",
+      "multiple.html",
+      "nocode.html",
+      "reference.html",
+      "snippets.html",
+      "some-xml.html",
+    ),
   )

plugin/src/sbt-test/paradox/template/build.sbt

@@ -3,5 +3,6 @@ lazy val templateTest = project
   .enablePlugins(ParadoxPlugin)
   .settings(
     // set the generic theme to test overriding page.st
-    paradoxTheme := Some(builtinParadoxTheme("generic"))
+    paradoxTheme := Some(builtinParadoxTheme("generic")),
+    paradoxRoots := List("page.html"),
   )