Merge branch 'master' into master

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

@@ -43,16 +43,14 @@ class ParadoxProcessor(reader: Reader = new Reader, writer: Writer = new Writer)
               errorListener: STErrorListener): Seq[(File, String)] = {
     val pages = parsePages(mappings, Path.replaceSuffix(sourceSuffix, targetSuffix))
     val paths = Page.allPaths(pages).toSet
-    // TODO: We assume there that all source files are contained in the same folder, maybe check if it's true
-    val rootPath = Path.relativeRootPath(mappings.head._1, mappings.head._2)
-    val globalPageMappings = rootPageMappings(rootPath, pages)
+    val globalPageMappings = rootPageMappings(pages)
 
     @tailrec
     def render(location: Option[Location[Page]], rendered: Seq[(File, String)] = Seq.empty): Seq[(File, String)] = location match {
       case Some(loc) =>
         val page = loc.tree.label
         val pageProperties = properties ++ page.properties.get
-        val currentMapping = Path.generateTargetFile(Path.relativeLocalPath(rootPath, page.file.getPath), globalPageMappings)_
+        val currentMapping = Path.generateTargetFile(Path.relativeLocalPath(page.rootSrcPage, page.file.getPath), globalPageMappings)_
         val writerContext = Writer.Context(loc, paths, currentMapping, sourceSuffix, targetSuffix, pageProperties)
         val pageToc = new TableOfContents(pages = true, headers = false, ordered = false, maxDepth = navigationDepth)
         val headerToc = new TableOfContents(pages = false, headers = true, ordered = false, maxDepth = navigationDepth)
@@ -176,14 +174,14 @@ class ParadoxProcessor(reader: Reader = new Reader, writer: Writer = new Writer)
   /**
    * Create Mappings from page path to target file name
    */
-  def rootPageMappings(root: String, pages: Forest[Page]): Map[String, String] = {
+  def rootPageMappings(pages: Forest[Page]): Map[String, String] = {
     @tailrec
     def mapping(location: Option[Location[Page]], fileMappings: List[(String, String)] = Nil): List[(String, String)] = location match {
       case Some(loc) =>
         val page = loc.tree.label
         val fullSrcPath = page.file.getPath
         val curTargetPath = page.path
-        val curSrcPath = Path.relativeLocalPath(root, fullSrcPath)
+        val curSrcPath = Path.relativeLocalPath(page.rootSrcPage, fullSrcPath)
         val curMappings = (curSrcPath, curTargetPath)
         mapping(loc.next, curMappings :: fileMappings)
       case None => fileMappings

core/src/main/scala/com/lightbend/paradox/markdown/Page.scala

@@ -40,7 +40,7 @@ case class Header(path: String, label: Node) extends Linkable
 /**
  * Markdown page with target path, parsed markdown, and headers.
  */
-case class Page(file: File, path: String, label: Node, h1: Header, headers: Forest[Header], markdown: RootNode, properties: Page.Properties) extends Linkable {
+case class Page(file: File, path: String, rootSrcPage: String, label: Node, h1: Header, headers: Forest[Header], markdown: RootNode, properties: Page.Properties) extends Linkable {
   /**
    * Path to the root of the site.
    */
@@ -91,12 +91,13 @@ object Page {
     // TODO: get default label node from page index link?
     val properties = Page.Properties(page.properties)
     val targetPath = properties.convertToTarget(convertPath)(page.path)
+    val rootSrcPage = Path.relativeRootPath(page.file, page.path)
     val (h1, subheaders) = page.headers match {
       case h :: hs => (Header(h.label.path, h.label.markdown), h.children ++ hs)
       case hs      => (Header(targetPath, new SpecialTextNode(targetPath)), hs)
     }
     val headers = subheaders map (_ map (h => Header(h.path, h.markdown)))
-    Page(page.file, targetPath, h1.label, h1, headers, page.markdown, properties)
+    Page(page.file, targetPath, rootSrcPage, h1.label, h1, headers, page.markdown, properties)
   }
 
   /**

docs/src/main/paradox/features/multi-configuration.md

@@ -0,0 +1,21 @@
+Multi Configuration
+-------------------
+
+Paradox supports multiple sbt configurations. Each configuration is by default located to `src/configName` of the project, with the target directory defined as `target/paradox/site/configName`, `configName` corresponding to configuration.name of a particular configuration. There still remains the usual main project in `src/main` of course if you don't need multiple paradox project directories.
+
+To associate a configuration to paradox, use its settings, and change its default source and/or target directorie(s) if needed:
+
+```scala
+val SomeConfig = config("some-config")
+
+lazy val root = (project in file(".")).
+  enablePlugins(ParadoxPlugin).
+  settings(
+    paradoxTheme = Some(builtinParadoxTheme("generic")),
+    ParadoxPlugin.paradoxSettings(SomeConfig),
+    sourceDirectory in SomeConfig := baseDirectory.value / "src" / "configuration-source-directory",
+    (target in paradox) in SomeConfig := baseDirectory.value / "paradox" / "site" / "configuration-target-directory"
+  )
+```
+
+Now, either you run paradox on one configuration; "sbt someConfig:paradox" or you can run the main project with the usual way; "sbt paradox".

docs/src/main/paradox/features/overlay.md

@@ -0,0 +1,23 @@
+Documentation overlay
+---------------------
+
+It is possible to add one or more overlays to a paradox project. Their location can be defined at build level and is applied to all configurations in the project unless we overwrite it for a particular configuration.
+
+```scala
+val DocsFirst = config("docs-first")
+val DocsSecond = config("docs-second")
+
+lazy val root = (project in file(".")).
+  enablePlugins(ParadoxPlugin).
+  settings(
+    name := "Paradox Project",
+    paradoxTheme := Some(builtinParadoxTheme("generic")),
+    paradoxOverlayDirectories := Seq(baseDirectory.value / "src" / "docs-common"),
+    ParadoxPlugin.paradoxSettings(DocsFirst),
+    ParadoxPlugin.paradoxSettings(DocsSecond),
+    paradoxOverlayDirectories in DocsFirst := Seq(baseDirectory.value / "src" / "docs-first-common", baseDirectory.value / "src" / "docs-second-common")
+  )
+```
+
+Markdown source files from the overlay directories are merged with the ones in the main project directory and are generated as if they were part of this latest.
+If a file duplicate exist between the directories, the overlay file is dropped in favour of the main directory file.

docs/src/main/paradox/index.md

@@ -25,17 +25,19 @@ lazy val root = (project in file(".")).
   )
 ```
 
-Then call `paradox` which will generate the site in `target/paradox/site/`.
+Then call `paradox` which will generate the site in `target/paradox/site/main`.
 
 Your markdown documentation will go inside `src/main/paradox/`. For example, you can start with `src/main/paradox/index.md`.
 
 ### Key features
 
+- Supports Multi-configuration
 - Supports Github flavored Markdown powered by [Pegdown][].
 - Principled markdown extension using generic directives syntax.
 - Github-friendly Markdown source (links work).
 - Code snippet inclusion for compilable code examples.
 - Templating and theming.
+- Documentation overlay.
 
 ### Generic directive
 
@@ -49,13 +51,15 @@ which basically means that all of our extensions would start with `@` (for inlin
 
 @@@ index
 
+* [Multi Configuration](features/multi-configuration.md)
 * [Organizing pages](features/organizing-pages.md)
 * [Linking](features/linking.md)
 * [Snippet inclusion](features/snippet-inclusion.md)
 * [Callouts](features/callouts.md)
 * [CSS Friendliness](features/css-friendliness.md)
 * [Templating](features/templating.md)
 * [Theming](features/theming.md)
+* [Documentation Overlay](features/documentation-overlay.md)
 
 @@@
 

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

@@ -32,6 +32,7 @@ trait ParadoxKeys {
   val paradoxTargetSuffix = settingKey[String]("Target file suffix for HTML files [default = \".html\"].")
   val paradoxTheme = settingKey[Option[ModuleID]]("Web module name of the paradox theme, otherwise local template.")
   val paradoxThemeDirectory = taskKey[File]("Sync combined theme and local template to a directory.")
+  val paradoxOverlayDirectories = settingKey[Seq[File]]("Directory containing common source files for configuration.")
   val paradoxTemplate = taskKey[PageTemplate]("PageTemplate to use when generating HTML pages.")
   val paradoxVersion = settingKey[String]("Paradox plugin version.")
 }

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

@@ -35,7 +35,7 @@ object ParadoxPlugin extends AutoPlugin {
 
   override def trigger = noTrigger
 
-  override def projectSettings: Seq[Setting[_]] = paradoxGlobalSettings ++ inConfig(Compile)(paradoxSettings)
+  override def projectSettings: Seq[Setting[_]] = paradoxSettings(Compile)
 
   def paradoxGlobalSettings: Seq[Setting[_]] = Seq(
     paradoxOrganization := readProperty("paradox.properties", "paradox.organization"),
@@ -49,9 +49,16 @@ object ParadoxPlugin extends AutoPlugin {
     libraryDependencies ++= paradoxTheme.value.toSeq
   )
 
-  def paradoxSettings: Seq[Setting[_]] = Seq(
+  def paradoxSettings(config: Configuration): Seq[Setting[_]] = paradoxGlobalSettings ++ inConfig(config)(Seq(
     paradoxProcessor := new ParadoxProcessor,
 
+    sourceDirectory := {
+      if (config.name != Compile.name)
+        sourceDirectory.value / config.name
+      else
+        sourceDirectory.value
+    },
+
     name in paradox := name.value,
     version in paradox := version.value,
     description in paradox := description.value,
@@ -65,8 +72,10 @@ object ParadoxPlugin extends AutoPlugin {
     paradoxProperties ++= dateProperties,
     paradoxProperties ++= linkProperties(scalaVersion.value, apiURL.value, scmInfo.value),
 
+    paradoxOverlayDirectories := Nil,
+
     sourceDirectory in paradox := sourceDirectory.value / "paradox",
-    sourceDirectories in paradox := Seq((sourceDirectory in paradox).value),
+    sourceDirectories in paradox := Seq((sourceDirectory in paradox).value) ++ paradoxOverlayDirectories.value,
 
     includeFilter in paradoxMarkdownToHtml := "*.md",
     excludeFilter in paradoxMarkdownToHtml := HiddenFileFilter,
@@ -137,12 +146,17 @@ object ParadoxPlugin extends AutoPlugin {
       val themeFilter = (managedSourceDirectories in paradoxTheme).value.headOption.map(InDirectoryFilter).getOrElse(NothingFilter)
       (mappings in Assets).value filterNot { case (file, path) => themeFilter.accept(file) }
     },
-    target in paradox := target.value / "paradox" / "site",
+    target in paradox := {
+      if (config.name != Compile.name)
+        target.value / "paradox" / "site" / config.name
+      else
+        target.value / "paradox" / "site" / "main"
+    },
 
     watchSources in Defaults.ConfigGlobal ++= (sourceDirectories in paradox).value.***.get,
 
     paradox := SbtWeb.syncMappings(streams.value.cacheDirectory, (mappings in paradox).value, (target in paradox).value)
-  )
+  ))
 
   def shortVersion(version: String): String = version.replace("-SNAPSHOT", "*")
 

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

@@ -0,0 +1,13 @@
+val DocsFirst = config("docs-first")
+val DocsSecond = config("docs-second")
+
+lazy val docs = (project in file(".")).
+  enablePlugins(ParadoxPlugin).
+  settings(
+    paradoxTheme := None,
+    ParadoxPlugin.paradoxSettings(DocsFirst),
+    ParadoxPlugin.paradoxSettings(DocsSecond),
+    // 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")
+  )

plugin/src/sbt-test/paradox/docs-overlay/expected/docs-first/docsFirstDir/docsFirstSubfile.html

@@ -0,0 +1,3 @@
+<h1><a href="#sub-main" name="sub-main" class="anchor"><span class="anchor-link"></span></a>Sub-main</h1>
+<p>go to <a href="../commonFirst.html">commonFirst</a></p>
+<p>go to <a href="../commonFirstDir/commonFirstFile.html">sub-commonFirst</a></p>

plugin/src/sbt-test/paradox/docs-overlay/expected/docs-first/docsFirstFile.html

@@ -0,0 +1,3 @@
+<h1><a href="#main" name="main" class="anchor"><span class="anchor-link"></span></a>Main</h1>
+<p>go to <a href="commonFirst.html">commonFirst</a></p>
+<p>go to <a href="commonFirstDir/commonFirstFile.html">sub-commonFirst</a></p>

plugin/src/sbt-test/paradox/docs-overlay/expected/docs-second/docsSecondDir/docsSecondSubfile.html

@@ -0,0 +1,5 @@
+<h1><a href="#sub-main" name="sub-main" class="anchor"><span class="anchor-link"></span></a>Sub-main</h1>
+<p>go to <a href="../commonFirst.html">commonFirst</a></p>
+<p>go to <a href="../commonFirstDir/commonFirstFile.html">sub-commonFirst</a></p>
+<p>go to <a href="../commonSecond.html">commonSecond</a></p>
+<p>go to <a href="../commonSecondDir/commonSecondFile.html">sub-commonSecond</a></p>

plugin/src/sbt-test/paradox/docs-overlay/expected/docs-second/docsSecondFile.html

@@ -0,0 +1,5 @@
+<h1><a href="#main" name="main" class="anchor"><span class="anchor-link"></span></a>Main</h1>
+<p>go to <a href="commonFirst.html">commonFirst</a></p>
+<p>go to <a href="commonFirstDir/commonFirstFile.html">sub-commonFirst</a></p>
+<p>go to <a href="commonSecond.html">commonSecond</a></p>
+<p>go to <a href="commonSecondDir/commonSecondFile.html">sub-commonSecond</a></p>

plugin/src/sbt-test/paradox/docs-overlay/project/plugins.sbt

@@ -0,0 +1 @@
+addSbtPlugin("com.lightbend.paradox" % "sbt-paradox" % sys.props("project.version"))

plugin/src/sbt-test/paradox/docs-overlay/src/docs-first/paradox/_template/page.st

@@ -0,0 +1 @@
+$page.content$

plugin/src/sbt-test/paradox/docs-overlay/src/docs-first/paradox/docsFirstDir/docsFirstSubfile.md

@@ -0,0 +1,5 @@
+#Sub-main
+
+go to @ref[commonFirst](../commonFirst.md)
+
+go to @ref[sub-commonFirst](../commonFirstDir/commonFirstFile.md)

plugin/src/sbt-test/paradox/docs-overlay/src/docs-first/paradox/docsFirstFile.md

@@ -0,0 +1,5 @@
+#Main
+
+go to @ref[commonFirst](commonFirst.md)
+
+go to @ref[sub-commonFirst](commonFirstDir/commonFirstFile.md)

plugin/src/sbt-test/paradox/docs-overlay/src/docs-second/paradox/_template/page.st

@@ -0,0 +1 @@
+$page.content$

plugin/src/sbt-test/paradox/docs-overlay/src/docs-second/paradox/docsSecondDir/docsSecondSubfile.md

@@ -0,0 +1,9 @@
+#Sub-main
+
+go to @ref[commonFirst](../commonFirst.md)
+
+go to @ref[sub-commonFirst](../commonFirstDir/commonFirstFile.md)
+
+go to @ref[commonSecond](../commonSecond.md)
+
+go to @ref[sub-commonSecond](../commonSecondDir/commonSecondFile.md)

plugin/src/sbt-test/paradox/docs-overlay/src/docs-second/paradox/docsSecondFile.md

@@ -0,0 +1,9 @@
+#Main
+
+go to @ref[commonFirst](commonFirst.md)
+
+go to @ref[sub-commonFirst](commonFirstDir/commonFirstFile.md)
+
+go to @ref[commonSecond](commonSecond.md)
+
+go to @ref[sub-commonSecond](commonSecondDir/commonSecondFile.md)

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

@@ -0,0 +1,14 @@
+> docs-first:paradox
+> docs-second:paradox
+
+$ must-mirror target/paradox/site/docs-first/docsFirstFile.html expected/docs-first/docsFirstFile.html
+$ must-mirror target/paradox/site/docs-first/docsFirstDir/docsFirstSubfile.html expected/docs-first/docsFirstDir/docsFirstSubfile.html
+$ must-mirror target/paradox/site/docs-first/commonFirst.html expected/docs-first/commonFirst.html
+$ must-mirror target/paradox/site/docs-first/commonFirstDir/commonFirstFile.html expected/docs-first/commonFirstDir/commonFirstFile.html
+
+$ must-mirror target/paradox/site/docs-second/docsSecondFile.html expected/docs-second/docsSecondFile.html
+$ must-mirror target/paradox/site/docs-second/docsSecondDir/docsSecondSubfile.html expected/docs-second/docsSecondDir/docsSecondSubfile.html
+$ must-mirror target/paradox/site/docs-second/commonFirst.html expected/docs-second/commonFirst.html
+$ must-mirror target/paradox/site/docs-second/commonFirstDir/commonFirstFile.html expected/docs-second/commonFirstDir/commonFirstFile.html
+$ must-mirror target/paradox/site/docs-second/commonSecond.html expected/docs-second/commonSecond.html
+$ must-mirror target/paradox/site/docs-second/commonSecondDir/commonSecondFile.html expected/docs-second/commonSecondDir/commonSecondFile.html

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

@@ -1,8 +1,8 @@
 > paradox
 
-$ must-mirror target/paradox/site/extref.html expected/extref.html
-$ must-mirror target/paradox/site/scaladoc.html expected/scaladoc.html
-$ must-mirror target/paradox/site/github.html expected/github.html
-$ must-mirror target/paradox/site/javadoc.html expected/javadoc.html
+$ must-mirror target/paradox/site/main/extref.html expected/extref.html
+$ must-mirror target/paradox/site/main/scaladoc.html expected/scaladoc.html
+$ must-mirror target/paradox/site/main/github.html expected/github.html
+$ must-mirror target/paradox/site/main/javadoc.html expected/javadoc.html
 
 > checkJavadocJavalibContent

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

@@ -1,3 +1,3 @@
 > paradox
 
-$ must-mirror target/paradox/site/scaladoc-2.12.html expected/scaladoc-2.12.html
+$ must-mirror target/paradox/site/main/scaladoc-2.12.html expected/scaladoc-2.12.html

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

@@ -1,12 +1,12 @@
 > paradox
 
-$ must-mirror target/paradox/site/a.html expected/a.html
-$ must-mirror target/paradox/site/a/a.html expected/a/a.html
-$ must-mirror target/paradox/site/a/b.html expected/a/b.html
-$ must-mirror target/paradox/site/a/c.html expected/a/c.html
-$ must-mirror target/paradox/site/b/a.html expected/b/a.html
-$ must-mirror target/paradox/site/b/a/a.html expected/b/a/a.html
-$ must-mirror target/paradox/site/b/b.html expected/b/b.html
-$ must-mirror target/paradox/site/c/a.html expected/c/a.html
-$ must-mirror target/paradox/site/css/page.css expected/css/page.css
-$ must-mirror target/paradox/site/images/a.png expected/images/a.png
+$ must-mirror target/paradox/site/main/a.html expected/a.html
+$ must-mirror target/paradox/site/main/a/a.html expected/a/a.html
+$ must-mirror target/paradox/site/main/a/b.html expected/a/b.html
+$ must-mirror target/paradox/site/main/a/c.html expected/a/c.html
+$ must-mirror target/paradox/site/main/b/a.html expected/b/a.html
+$ must-mirror target/paradox/site/main/b/a/a.html expected/b/a/a.html
+$ must-mirror target/paradox/site/main/b/b.html expected/b/b.html
+$ must-mirror target/paradox/site/main/c/a.html expected/c/a.html
+$ must-mirror target/paradox/site/main/css/page.css expected/css/page.css
+$ must-mirror target/paradox/site/main/images/a.png expected/images/a.png

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

@@ -1,8 +1,8 @@
 > paradox
 
-$ must-mirror target/paradox/site/snippets.html expected/snippets.html
-$ must-mirror target/paradox/site/reference.html expected/reference.html
-$ must-mirror target/paradox/site/multiple.html expected/multiple.html
-$ must-mirror target/paradox/site/some-xml.html expected/some-xml.html
-$ must-mirror target/paradox/site/nocode.html expected/nocode.html
-$ must-mirror target/paradox/site/configured-bases.html expected/configured-bases.html
+$ must-mirror target/paradox/site/main/snippets.html expected/snippets.html
+$ must-mirror target/paradox/site/main/reference.html expected/reference.html
+$ must-mirror target/paradox/site/main/multiple.html expected/multiple.html
+$ must-mirror target/paradox/site/main/some-xml.html expected/some-xml.html
+$ must-mirror target/paradox/site/main/nocode.html expected/nocode.html
+$ must-mirror target/paradox/site/main/configured-bases.html expected/configured-bases.html