Add more tests and docs

Author: Olafur Pall Geirsson

docs/installation.md

@@ -134,6 +134,8 @@ info: Compiling 1 file to website/target/docs
 info: Compiled in 1.2s (0 errors)
 ```
 
+### Add library dependencies to classpath
+
 Add libraries to the launched classpath to include them for compilation.
 
 ```diff
@@ -142,14 +144,18 @@ Add libraries to the launched classpath to include them for compilation.
 +  org.typelevel:cats-core_@SCALA_BINARY_VERSION@:1.5.0
 ```
 
-Use `--in` to customize the input directory where markdown sources are
-contained, by default the `docs/` directory is used.
+### Customize input directory
+
+By default the `docs/` directory is processed as input. Use `--in` to customize
+the input directory where markdown sources are contained,
 
 ```diff
  coursier launch org.scalameta:mdoc_@SCALA_BINARY_VERSION@:@VERSION@ -- \
 +  --in mydocs
 ```
 
+### Process single markdown file
+
 The `--in` flag doesn't have to be a directory, it also supports individual
 files.
 
@@ -158,6 +164,8 @@ files.
 +  --in mydocs/readme.md
 ```
 
+### Configure site variables like `@VERSION@`
+
 Use `--site.VARIABLE=value` to add site variables that can be referenced from
 markdown as `@@VARIABLE@`.
 
@@ -166,6 +174,8 @@ markdown as `@@VARIABLE@`.
 +  --site.SCALA_VERSION @SCALA_VERSION@
 ```
 
+### Customize output directory
+
 Use `--out` to customize where your markdown sources are generated, by default
 the `out/` directory is used.
 
@@ -174,15 +184,34 @@ the `out/` directory is used.
 +  --out target/docs
 ```
 
-The `--out` flag doesn't have to be a directory, it can also be an individual
-file. However, this assumes that your `--in` was also an individual file.
+### Generate single output file instead of directory
+
+The `--out` flag doesn't have to be a directory when the `--in` argument is a
+regular file, it can also be an individual file.
 
 ```diff
  coursier launch org.scalameta:mdoc_@SCALA_BINARY_VERSION@:@VERSION@ -- \
-+  --in mydocs/readme.template.md \
++  --in readme.template.md \
 +  --out readme.md
 ```
 
+### Process multiple input directories and files
+
+Repeat the `--in` and `--out` arguments to process multiple directories and
+regular files.
+
+```diff
+ coursier launch org.scalameta:mdoc_@SCALA_BINARY_VERSION@:@VERSION@ -- \
++  --in readme.template.md \
++  --out readme.md \
++  --in example.template.md \
++  --out example.md \
++  --in mydocs-directory \
++  --out out-directory \
+```
+
+### Live reload HTML preview on file save
+
 Use `--watch` to start the file watcher with livereload. It's recommended to use
 `--watch` while writing documentation to enjoy 3-4x faster compilation
 performance.

mdoc-docs/src/main/scala/mdoc/docs/SbtModifier.scala

@@ -39,5 +39,5 @@ class SbtModifier extends StringModifier {
       </tr>
       {rows}
     </table>
-  }.toString()
+  }.toString() + "\n\n"
 }

mdoc/src/main/scala/mdoc/internal/cli/InputFile.scala

@@ -23,6 +23,12 @@ case class InputFile(
 )
 
 object InputFile {
+  implicit val ordering: Ordering[InputFile] = new Ordering[InputFile] {
+    def compare(x: InputFile, y: InputFile): Int = {
+      x.inputFile.toNIO.compareTo(y.inputFile.toNIO)
+    }
+  }
+
   def fromSettings(filename: String, settings: Settings): InputFile = {
     val relpath = RelativePath(filename)
     val inputDir = settings.in.head

mdoc/src/main/scala/mdoc/internal/cli/MainOps.scala

@@ -133,7 +133,9 @@ final class MainOps(
   }
 
   def generateCompleteSite(): Exit = {
-    val files = IO.inputFiles(settings)
+    // NOTE(olafur): we sort the input files for reproducible output in cases
+    // where multiple input files write to the same output file.
+    val files = IO.inputFiles(settings).sorted
     val timer = new Timer()
     val n = files.length
     compilingFiles(n)

mdoc/src/main/scala/mdoc/internal/cli/Settings.scala

@@ -36,16 +36,15 @@ class Section(val name: String) extends StaticAnnotation
 case class Settings(
     @Section("Common options")
     @Description(
-      "The input directory containing markdown and other documentation sources " +
-        "or an individual file that you'd like to target. Markdown files will be " +
-        "processed by mdoc while other files will be copied verbatim to the output directory."
+      "The input directory or regular file containing markdown and other documentation sources that should be processed. " +
+        "Markdown files are processed by mdoc while non-markdown files are copied verbatim to the output directory. " +
+        "Can be repeated to process multiple input directories/files."
     )
     @ExtraName("i")
     in: List[AbsolutePath],
     @Description(
-      "The output directory where you'd like to generate your markdown or other documentation " +
-        "sources. This can also be an individual filename, but it then assumes that your `--in` " +
-        "was also an indiviudal file."
+      "The output directory or regular where you'd like to generate your markdown or other documentation sources. " +
+        "Must be repeated to match the number of `--in` arguments and must be a directory when the matching `--in` argument is a directory."
     )
     @ExtraName("o")
     out: List[AbsolutePath],
@@ -303,11 +302,13 @@ object Settings extends MetaconfigScalametaImplicits {
     s"mdoc v$displayVersion"
   def usage: String =
     """|Usage:   mdoc [<option> ...]
-       |Example: mdoc --in <path> --out <path> (customize input/output directories)
+       |Example: mdoc --in mydocs --out _site  (custom input/output directories)
        |         mdoc --watch                  (watch for file changes)
        |         mdoc --site.VERSION 1.0.0     (pass in site variables)
        |         mdoc --include **/example.md  (process only files named example.md)
        |         mdoc --exclude node_modules   (don't process node_modules directory)
+       |         mdoc --in readme.template.md --out readme.md \
+       |              --in examples.template.md --out examples.md (multiple input/output pairs)
        |""".stripMargin
   def description: Doc =
     Doc.paragraph(

tests/unit/src/test/scala/tests/cli/CliSuite.scala

@@ -291,4 +291,64 @@ class CliSuite extends BaseCliSuite {
     extraArgs = Array("--in", "index2.md", "--out", out().resolve("out2.md").toString)
   )
 
+  checkCli(
+    "multiple-out-directories",
+    """
+      |/in1/index.md
+      |```scala mdoc
+      |println("1 file")
+      |```
+      |/in2/index.md
+      |```scala mdoc
+      |println("2 file")
+      |```
+      |/in3/index.md
+      |```scala mdoc
+      |println("3 file")
+      |```
+      |""".stripMargin,
+    """
+      |/out1/index.md
+      |```scala
+      |println("1 file")
+      |// 1 file
+      |```
+      |/out2/index.md
+      |```scala
+      |println("2 file")
+      |// 2 file
+      |```
+      |""".stripMargin,
+    input = "in1",
+    output = out().resolve("out1").toString,
+    extraArgs = Array("--in", "in2", "--out", out().resolve("out2").toString)
+  )
+
+  checkCli(
+    "conflicting-out",
+    """
+      |/in1/index.md
+      |```scala mdoc
+      |println("1 file")
+      |```
+      |/in2/index.md
+      |```scala mdoc
+      |println("2 file")
+      |```
+      |""".stripMargin,
+    // NOTE(olafur) Last one wins in case of conflict. Feel free to update the
+    // expected behavior here if we want to error instead. This test is only to
+    // document that the current behavior even if this behavior is undesirable.
+    """
+      |/out/index.md
+      |```scala
+      |println("2 file")
+      |// 2 file
+      |```
+      |""".stripMargin,
+    input = "in1",
+    output = out().resolve("out").toString,
+    extraArgs = Array("--in", "in2", "--out", out().resolve("out").toString)
+  )
+
 }