Support multiple input/output file/directory pairs.

Previously, mdoc only supported a single --in and --out argument and
they both had to be directories. Now, users can specify a list of
--in and --out arguments of both files and directories.

This change enables nice use-cases like generating a single `readme.md`
file in the root directory of a git repo or generating the blog
directory of a Docusaurus website.
```
mdoc --in readme.template.md --out readme.md
mdoc --in docs --out website/target/docs --in blog --out website/blog
```

This change turned out to be tricky to implement:

* the public API for custom modifiers needs to correctly handle the case
  when --in and --out are files. For example, the Scala.js modifier needs
  to be able to know where to generate JavaScript files.
* we need to report helpful and actionable error messages when
  validating user input. For example, it's not valid to pair an input
  directory with an output file.

Author: Olafur Pall Geirsson

build.sbt

@@ -9,6 +9,7 @@ inThisBuild(
     scalaVersion := scala212,
     crossScalaVersions := List(scala212, scala211, scala213),
     scalacOptions ++= List(
+      "-Yrangepos",
       "-Xexperimental",
       "-deprecation"
     ),

docs/installation.md

@@ -119,7 +119,6 @@ The sbt-mdoc plugin supports the following settings.
 
 ```
 
-
 ## Command-line
 
 Use [coursier](https://github.com/coursier/coursier/#command-line) to launch
@@ -167,16 +166,16 @@ markdown as `@@VARIABLE@`.
 +  --site.SCALA_VERSION @SCALA_VERSION@
 ```
 
-Use `--out` to customize where your markdown sources are generated, by
-default the `out/` directory is used.
+Use `--out` to customize where your markdown sources are generated, by default
+the `out/` directory is used.
 
 ```diff
  coursier launch org.scalameta:mdoc_@SCALA_BINARY_VERSION@:@VERSION@ -- \
 +  --out target/docs
 ```
 
 The `--out` flag doesn't have to be a directory, it can also be an individual
-file. However, this assume that your `--in` was also an individual file.
+file. However, this assumes that your `--in` was also an individual file.
 
 ```diff
  coursier launch org.scalameta:mdoc_@SCALA_BINARY_VERSION@:@VERSION@ -- \

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

@@ -14,6 +14,7 @@ import mdoc.internal.markdown.GitHubIdGenerator
 import mdoc.internal.markdown.LinkHygiene
 import mdoc.internal.pos.PositionSyntax._
 import mdoc.internal.markdown.MarkdownFile
+import mdoc.internal.cli.InputFile
 
 class MdocModifier(context: Context) extends StringModifier {
   private val myStdout = new ByteArrayOutputStream()
@@ -24,16 +25,16 @@ class MdocModifier(context: Context) extends StringModifier {
     myStdout.reset()
     myReporter.reset()
     val cleanInput = Input.VirtualFile(code.filename, code.text)
-    val relpath = RelativePath(code.filename)
+    val file = InputFile.fromSettings(code.filename, context.settings)
     val markdown = Markdown.toMarkdown(
       cleanInput,
       myContext,
-      relpath,
+      file,
       myContext.settings.site,
       myReporter,
       myContext.settings
     )
-    val links = DocumentLinks.fromMarkdown(GitHubIdGenerator, relpath, cleanInput)
+    val links = DocumentLinks.fromMarkdown(GitHubIdGenerator, file.relpath, cleanInput)
     LinkHygiene.lint(List(links), myReporter, verbose = false)
     val stdout = fansi.Str(myStdout.toString()).plainText
     if (myReporter.hasErrors || myReporter.hasWarnings) {

mdoc-js/src/main/scala-2.12/mdoc/modifiers/JsConfig.scala

@@ -15,7 +15,8 @@ case class JsConfig(
     libraries: List[AbsolutePath] = Nil,
     mountNode: String = "node",
     minLevel: Level = Level.Info,
-    outDirectory: AbsolutePath = PathIO.workingDirectory,
+    outDirectories: List[AbsolutePath] = List(PathIO.workingDirectory),
+    outPrefix: Option[String] = None,
     fullOpt: Boolean = true,
     htmlPrefix: String = "",
     relativeLinkPrefix: String = ""
@@ -65,14 +66,8 @@ object JsConfig {
       ctx.site.getOrElse("js-html-header", ""),
       Classpath(ctx.site.getOrElse("js-libraries", "")).entries,
       mountNode = ctx.site.getOrElse("js-mount-node", base.mountNode),
-      outDirectory = ctx.site.get("js-out-prefix") match {
-        case Some(value) =>
-          // This is needed for Docusaurus that requires assets (non markdown) files to live under
-          // `docs/assets/`: https://docusaurus.io/docs/en/doc-markdown#linking-to-images-and-other-assets
-          ctx.settings.out.resolve(value)
-        case None =>
-          ctx.settings.out
-      },
+      outDirectories = ctx.settings.out,
+      outPrefix = ctx.site.get("js-out-prefix"),
       minLevel = ctx.site.get("js-level") match {
         case None => Level.Info
         case Some("info") => Level.Info

mdoc-js/src/main/scala-2.12/mdoc/modifiers/JsModifier.scala

@@ -25,6 +25,8 @@ import scala.meta.Term
 import scala.meta.inputs.Input
 import scala.meta.io.Classpath
 import scala.reflect.io.VirtualDirectory
+import mdoc.internal.cli.InputFile
+import scala.meta.io.AbsolutePath
 
 class JsModifier extends mdoc.PreModifier {
   override val name = "js"
@@ -153,19 +155,40 @@ class JsModifier extends mdoc.PreModifier {
     } else {
       val output = WritableMemVirtualJSFile("output.js")
       linker.link(virtualIrFiles ++ sjsir, Nil, output, sjsLogger)
-      val outjsfile = config.outDirectory.resolve(ctx.relativePath.resolveSibling(_ + ".js"))
-      outjsfile.write(output.content)
-      val outmdoc = outjsfile.resolveSibling(_ => "mdoc.js")
-      outmdoc.write(Resources.readPath("/mdoc.js"))
-      val relfile = outjsfile.toRelativeLinkFrom(ctx.outputFile, config.relativeLinkPrefix)
-      val relmdoc = outmdoc.toRelativeLinkFrom(ctx.outputFile, config.relativeLinkPrefix)
-      new CodeBuilder()
-        .println(config.htmlHeader)
-        .lines(config.libraryScripts(outjsfile, ctx))
-        .println(s"""<script type="text/javascript" src="$relfile" defer></script>""")
-        .println(s"""<script type="text/javascript" src="$relmdoc" defer></script>""")
-        .toString
+      ctx.settings.toInputFile(ctx.inputFile) match {
+        case None =>
+          ctx.reporter.error(
+            s"unable to find output file matching the input file '${ctx.inputFile}'. " +
+              s"To fix this problem, make sure that  --in points to a directory that contains the file ${ctx.inputFile}."
+          )
+          ""
+        case Some(inputFile) =>
+          val outjsfile = resolveOutputJsFile(inputFile)
+          outjsfile.write(output.content)
+          val outmdoc = outjsfile.resolveSibling(_ => "mdoc.js")
+          outmdoc.write(Resources.readPath("/mdoc.js"))
+          val relfile = outjsfile.toRelativeLinkFrom(ctx.outputFile, config.relativeLinkPrefix)
+          val relmdoc = outmdoc.toRelativeLinkFrom(ctx.outputFile, config.relativeLinkPrefix)
+          new CodeBuilder()
+            .println(config.htmlHeader)
+            .lines(config.libraryScripts(outjsfile, ctx))
+            .println(s"""<script type="text/javascript" src="$relfile" defer></script>""")
+            .println(s"""<script type="text/javascript" src="$relmdoc" defer></script>""")
+            .toString
+      }
+    }
+  }
+
+  private def resolveOutputJsFile(file: InputFile): AbsolutePath = {
+    val outputDirectory = config.outPrefix match {
+      case None =>
+        file.outputDirectory
+      case Some(prefix) =>
+        // This is needed for Docusaurus that requires assets (non markdown) files to live under
+        // `docs/assets/`: https://docusaurus.io/docs/en/doc-markdown#linking-to-images-and-other-assets
+        file.outputDirectory.resolve(prefix)
     }
+    outputDirectory.resolve(file.relpath).resolveSibling(_ + ".js")
   }
 
   override def process(ctx: PreModifierContext): String = {

mdoc/src/main/scala/mdoc/MainSettings.scala

@@ -44,10 +44,16 @@ final class MainSettings private (
     copy(settings.withWorkingDirectory(AbsolutePath(cwd)))
   }
   def withOut(out: Path): MainSettings = {
-    copy(settings.copy(out = AbsolutePath(out)))
+    withOutputPaths(List(out))
+  }
+  def withOutputPaths(out: List[Path]): MainSettings = {
+    copy(settings.copy(out = out.map(AbsolutePath(_)(settings.cwd))))
   }
   def withIn(in: Path): MainSettings = {
-    copy(settings.copy(in = AbsolutePath(in)))
+    withInputPaths(List(in))
+  }
+  def withInputPaths(in: List[Path]): MainSettings = {
+    copy(settings.copy(in = in.map(AbsolutePath(_)(settings.cwd))))
   }
   def withClasspath(classpath: String): MainSettings = {
     copy(settings.copy(classpath = classpath))

mdoc/src/main/scala/mdoc/OnLoadContext.scala

@@ -0,0 +1,10 @@
+package mdoc
+
+import mdoc.internal.cli.Settings
+
+final class OnLoadContext private[mdoc] (
+    val reporter: Reporter,
+    private[mdoc] val settings: Settings
+) {
+  def site: Map[String, String] = settings.site
+}

mdoc/src/main/scala/mdoc/PostModifier.scala

@@ -10,6 +10,7 @@ import scala.meta.inputs.Input
 import scala.meta.io.AbsolutePath
 import scala.collection.JavaConverters._
 import scala.meta.io.RelativePath
+import mdoc.internal.cli.InputFile
 
 trait PostModifier {
   val name: String
@@ -33,12 +34,13 @@ final class PostModifierContext private[mdoc] (
     val outputCode: String,
     val variables: List[Variable],
     val reporter: Reporter,
-    val relativePath: RelativePath,
+    private[mdoc] val file: InputFile,
     private[mdoc] val settings: Settings
 ) {
-  def inputFile: AbsolutePath = inDirectory.resolve(relativePath)
-  def outputFile: AbsolutePath = outDirectory.resolve(relativePath)
   def lastValue: Any = variables.lastOption.map(_.runtimeValue).orNull
-  def inDirectory: AbsolutePath = settings.in
-  def outDirectory: AbsolutePath = settings.out
+  def relativePath: RelativePath = file.relpath
+  def inputFile: AbsolutePath = file.inputFile
+  def outputFile: AbsolutePath = file.outputFile
+  def inDirectory: AbsolutePath = file.inputDirectory
+  def outDirectory: AbsolutePath = file.outputDirectory
 }

mdoc/src/main/scala/mdoc/PostProcessContext.scala

@@ -0,0 +1,18 @@
+package mdoc
+
+import scala.meta.io.AbsolutePath
+import scala.meta.io.RelativePath
+import mdoc.internal.cli.Settings
+import mdoc.internal.cli.InputFile
+
+final class PostProcessContext private[mdoc] (
+    val reporter: Reporter,
+    private[mdoc] val file: InputFile,
+    private[mdoc] val settings: Settings
+) {
+  def relativePath: RelativePath = file.relpath
+  def inputFile: AbsolutePath = file.inputFile
+  def outputFile: AbsolutePath = file.outputFile
+  def inDirectory: AbsolutePath = file.inputDirectory
+  def outDirectory: AbsolutePath = file.outputDirectory
+}

mdoc/src/main/scala/mdoc/PreModifier.scala

@@ -30,40 +30,3 @@ object PreModifier {
   implicit val encoder: ConfEncoder[PreModifier] =
     ConfEncoder.StringEncoder.contramap(mod => s"<${mod.name}>")
 }
-
-final class OnLoadContext private[mdoc] (
-    val reporter: Reporter,
-    private[mdoc] val settings: Settings
-) {
-  def site: Map[String, String] = settings.site
-}
-
-final class PostProcessContext private[mdoc] (
-    val reporter: Reporter,
-    val relativePath: RelativePath,
-    private[mdoc] val settings: Settings
-) {
-  def inputFile: AbsolutePath = inDirectory.resolve(relativePath)
-  def outputFile: AbsolutePath = outDirectory.resolve(relativePath)
-  def inDirectory: AbsolutePath = settings.in
-  def outDirectory: AbsolutePath = settings.out
-}
-
-final class PreModifierContext private[mdoc] (
-    val info: String,
-    val originalCode: Input,
-    val reporter: Reporter,
-    val relativePath: RelativePath,
-    private[mdoc] val settings: Settings
-) {
-  def infoInput: Input = {
-    val cpos = originalCode.toPosition.toUnslicedPosition
-    val start = cpos.start - info.length - 1
-    val end = cpos.start - 1
-    Input.Slice(cpos.input, start, end)
-  }
-  def inputFile: AbsolutePath = inDirectory.resolve(relativePath)
-  def outputFile: AbsolutePath = outDirectory.resolve(relativePath)
-  def inDirectory: AbsolutePath = settings.in
-  def outDirectory: AbsolutePath = settings.out
-}

mdoc/src/main/scala/mdoc/PreModifierContext.scala

@@ -0,0 +1,28 @@
+package mdoc
+
+import scala.meta.inputs.Input
+import scala.meta.io.RelativePath
+import mdoc.internal.cli.Settings
+import mdoc.internal.pos.PositionSyntax._
+import scala.meta.io.AbsolutePath
+import mdoc.internal.cli.InputFile
+
+final class PreModifierContext private[mdoc] (
+    val info: String,
+    val originalCode: Input,
+    val reporter: Reporter,
+    private[mdoc] val file: InputFile,
+    private[mdoc] val settings: Settings
+) {
+  def infoInput: Input = {
+    val cpos = originalCode.toPosition.toUnslicedPosition
+    val start = cpos.start - info.length - 1
+    val end = cpos.start - 1
+    Input.Slice(cpos.input, start, end)
+  }
+  def relativePath: RelativePath = file.relpath
+  def inputFile: AbsolutePath = file.inputFile
+  def outputFile: AbsolutePath = file.outputFile
+  def inDirectory: AbsolutePath = file.inputDirectory
+  def outDirectory: AbsolutePath = file.outputDirectory
+}

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

@@ -1,6 +1,7 @@
 package mdoc.internal.cli
 
 import java.nio.file.Path
+import scala.meta.io.AbsolutePath
 
 object Feedback {
   def outSubdirectoryOfIn(in: Path, out: Path): String = {
@@ -9,4 +10,24 @@ object Feedback {
       s"  --in=$in\n" +
       s"  --out=$out"
   }
+  def mustBeNonEmpty(what: String): String = {
+    s"--$what must be non-empty. To fix this problem, add an argument for the `--$what <value>` argument."
+  }
+  def inputDifferentLengthOutput(input: List[AbsolutePath], output: List[AbsolutePath]): String = {
+    val diff = math.abs(input.length - output.length)
+    val toFix = if (input.length > output.length) "out" else "in"
+    s"--in and --out must have the same length but found ${input.length} --in argument(s) and ${output.length} --out argument(s). " +
+      s"To fix this problem, add $diff more $toFix arguments."
+  }
+  def outputCannotBeRegularFile(input: AbsolutePath, output: AbsolutePath): String = {
+    s"--out argument '$output' cannot be a regular file when --in argument '$input' is a directory."
+  }
+  def outputCannotBeDirectory(input: AbsolutePath, output: AbsolutePath): String = {
+    s"--out argument '$output' cannot be a directory when --in argument '$input' is a regular file. " +
+      "To fix this problem, change the --out argument to point to a regular file or an empty path."
+  }
+  def inputEqualOutput(input: AbsolutePath): String = {
+    s"--in and --out cannot be the same path '$input'. " +
+      "To fix this problem, change the --out argument to another path."
+  }
 }

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

@@ -2,9 +2,31 @@ package mdoc.internal.cli
 
 import scala.meta.io.AbsolutePath
 import scala.meta.io.RelativePath
+import scala.meta.internal.io.PathIO
+import metaconfig.Input
+import java.nio.file.Files
+import mdoc.internal.pos.PositionSyntax._
 
+/**
+  * @param relpath the input filename relativized by its input directory.
+  * @param inputFile the input file to read from.
+  * @param outputFile the output file to write to.
+  * @param inputDirectory directory enclosing the input file.
+  * @param outputDirectory directory enclosing the output file.
+  */
 case class InputFile(
     relpath: RelativePath,
-    in: AbsolutePath,
-    out: AbsolutePath
+    inputFile: AbsolutePath,
+    outputFile: AbsolutePath,
+    inputDirectory: AbsolutePath,
+    outputDirectory: AbsolutePath
 )
+
+object InputFile {
+  def fromSettings(filename: String, settings: Settings): InputFile = {
+    val relpath = RelativePath(filename)
+    val inputDir = settings.in.head
+    val outputDir = settings.out.head
+    InputFile(relpath, inputDir.resolve(filename), outputDir.resolve(filename), inputDir, outputDir)
+  }
+}