Target a single file for --in and --out

build.sbt

@@ -9,6 +9,7 @@ inThisBuild(
     scalaVersion := scala212,
     crossScalaVersions := List(scala212, scala211, scala213),
     scalacOptions ++= List(
+      "-Yrangepos",
       "-Xexperimental",
       "-deprecation"
     ),
@@ -36,7 +37,8 @@ inThisBuild(
     // faster publishLocal:
     publishArtifact.in(packageDoc) := "true" == System.getenv("CI"),
     publishArtifact.in(packageSrc) := "true" == System.getenv("CI"),
-    turbo := true
+    turbo := true,
+    useSuperShell := false // overlaps with MUnit test failure reports.
   )
 )
 

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
@@ -135,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
@@ -143,14 +144,28 @@ 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.
+
+```diff
+ coursier launch org.scalameta:mdoc_@SCALA_BINARY_VERSION@:@VERSION@ -- \
++  --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@`.
 
@@ -159,14 +174,44 @@ markdown as `@@VARIABLE@`.
 +  --site.SCALA_VERSION @SCALA_VERSION@
 ```
 
-Use `--out` to customize the directory where markdown sources are generated, by
-default the `out/` directory is used.
+### Customize output directory
+
+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
 ```
 
+### 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 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 changelog.template.md \
++  --out changelog.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/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-docs/src/main/scala/mdoc/docs/SbtModifier.scala

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

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-sbt/src/main/scala/mdoc/MdocPlugin.scala

@@ -18,13 +18,14 @@ object MdocPlugin extends AutoPlugin {
       )
     val mdocIn =
       settingKey[File](
-        "Input directory containing markdown sources to be processed by mdoc. " +
+        "Input directory or source file containing markdown to be processed by mdoc. " +
           "Defaults to the toplevel docs/ directory."
       )
     val mdocOut =
       settingKey[File](
-        "Output directory for mdoc generated markdown. " +
-          "Defaults to the target/mdoc directory of this project."
+        "Output directory or output file name for mdoc generated markdown. " +
+          "Defaults to the target/mdoc directory of this project. " +
+          "If this is a file name, it assumes your `in` was also an individual file"
       )
     val mdocExtraArguments =
       settingKey[Seq[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
-}