add ability to specify an out file

docs/installation.md

@@ -167,14 +167,23 @@ markdown as `@@VARIABLE@`.
 +  --site.SCALA_VERSION @SCALA_VERSION@
 ```
 
-Use `--out` to customize the directory where markdown sources are generated, by
+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.
+
+```diff
+ coursier launch org.scalameta:mdoc_@SCALA_BINARY_VERSION@:@VERSION@ -- \
++  --in mydocs/readme.template.md \
++  --out readme.md
+```
+
 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-sbt/src/main/scala/mdoc/MdocPlugin.scala

@@ -23,8 +23,9 @@ object MdocPlugin extends AutoPlugin {
       )
     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 indidivual file"
       )
     val mdocExtraArguments =
       settingKey[Seq[String]](

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

@@ -121,7 +121,7 @@ final class MainOps(
   }
 
   def generateCompleteSite(): Exit = {
-    val isFile = settings.in.toFile.isFile
+    val isFile = Files.isRegularFile(settings.in.toNIO)
     val files = if (isFile) {
       settings.toInputFile(settings.in).toList
     } else {

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

@@ -41,7 +41,11 @@ case class Settings(
     )
     @ExtraName("i")
     in: AbsolutePath,
-    @Description("The output directory to generate the mdoc site.")
+    @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."
+    )
     @ExtraName("o")
     out: AbsolutePath,
     @Description("Start a file watcher and incrementally re-generate the site on file save.")
@@ -161,21 +165,27 @@ case class Settings(
   def isFileWatching: Boolean = watch && !check
 
   def toInputFile(infile: AbsolutePath): Option[InputFile] = {
-    val relpath = if (infile == in) {
+    val relativeIn = if (infile == in) {
       RelativePath(in.toNIO.getFileName.toString)
     } else {
       infile.toRelative(in)
     }
-    if (isIncluded(relpath)) {
-      val outfile = out.resolve(relpath)
-      Some(InputFile(relpath, infile, outfile))
+    if (isIncluded(relativeIn)) {
+      val outfile = if (assumedRegularFile(out)) {
+        out
+      } else {
+        out.resolve(relativeIn)
+      }
+      Some(InputFile(relativeIn, infile, outfile))
     } else {
       None
     }
   }
+
   def isExplicitlyExcluded(path: RelativePath): Boolean = {
     exclude.exists(_.matches(path.toNIO))
   }
+
   def isIncluded(path: RelativePath): Boolean = {
     (include.isEmpty || include.exists(_.matches(path.toNIO))) &&
     !isExplicitlyExcluded(path)
@@ -185,10 +195,13 @@ case class Settings(
     val ctx = new OnLoadContext(reporter, this)
     preModifiers.foreach(_.onLoad(ctx))
   }
+
   def validate(logger: Reporter): Configured[Context] = {
     if (Files.exists(in.toNIO)) {
-      if (out.toNIO.startsWith(in.toNIO)) {
+      if (out.toNIO.startsWith(in.toNIO) && !assumedRegularFile(out)) {
         Configured.error(Feedback.outSubdirectoryOfIn(in.toNIO, out.toNIO))
+      } else if (assumedRegularFile(out) && Files.isDirectory(in.toNIO)) {
+        Configured.error("your 'in' must be a file if 'out' is a file")
       } else {
         val compiler = MarkdownCompiler.fromClasspath(classpath, scalacOptions)
         onLoad(logger)
@@ -202,13 +215,12 @@ case class Settings(
       ConfError.fileDoesNotExist(in.toNIO).notOk
     }
   }
-  def resolveIn(relpath: RelativePath): AbsolutePath = {
-    in.resolve(relpath)
-  }
 
-  def resolveOut(relpath: RelativePath): AbsolutePath = {
-    out.resolve(relpath)
+  private def assumedRegularFile(absPath: AbsolutePath): Boolean = {
+    val extension = PathIO.extension(absPath.toNIO)
+    markdownExtensions.toSet.contains(extension)
   }
+
   def withWorkingDirectory(dir: AbsolutePath): Settings = {
     copy(
       in = dir.resolve("docs"),

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

@@ -19,7 +19,8 @@ abstract class BaseCliSuite extends FunSuite {
       expected: String,
       extraArgs: Array[String] = Array.empty,
       setup: CliFixture => Unit = _ => (),
-      configureInFlag: AbsolutePath => String = _.toString(),
+      configureInFlag: AbsolutePath => String = _.toString,
+      configureOutFlag: Path => String = _.toString,
       expectedExitCode: Int = 0,
       onStdout: String => Unit = _ => ()
   ): Unit = {
@@ -32,7 +33,7 @@ abstract class BaseCliSuite extends FunSuite {
         "--in",
         configureInFlag(in),
         "--out",
-        out.toString,
+        configureOutFlag(out),
         "--cwd",
         in.toString,
         "--site.version",

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

@@ -36,6 +36,12 @@ class CliArgsSuite extends FunSuite {
     s"File $tmp does not exist."
   )
 
+  private val anotherTemp = Files.createTempDirectory("mdoc")
+  checkError(
+    "--in" :: anotherTemp.toString :: "--out" :: "fake.md" :: Nil,
+    "your 'in' must be a file if 'out' is a file"
+  )
+
   checkOk(
     "--site.VERSION" :: "1.0" :: Nil,
     _.site == Map("VERSION" -> "1.0")

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

@@ -190,7 +190,7 @@ class CliSuite extends BaseCliSuite {
   )
 
   checkCli(
-    "single-file",
+    "single-in",
     """
       |/index.md
       |# Single file
@@ -206,7 +206,77 @@ class CliSuite extends BaseCliSuite {
       |// one file
       |```
       |""".stripMargin,
-    configureInFlag = { in => in + "/index.md" }
+    configureInFlag = { in => in.resolve("index.md").toString }
+  )
+
+  checkCli(
+    "single-in-only",
+    """
+      |/index.md
+      |# Single file
+      |```scala mdoc
+      |println("one file")
+      |```
+      |/second.md
+      |```scala mdoc
+      |println("second file")
+      |```
+      |""".stripMargin,
+    """
+      |/index.md
+      |# Single file
+      |```scala
+      |println("one file")
+      |// one file
+      |```
+      |""".stripMargin,
+    configureInFlag = { in => in.resolve("index.md").toString }
+  )
+
+  checkCli(
+    "single-in-single-out",
+    """
+      |/index.md
+      |# Single file
+      |```scala mdoc
+      |println("one file")
+      |```
+      |""".stripMargin,
+    """
+      |/out.md
+      |# Single file
+      |```scala
+      |println("one file")
+      |// one file
+      |```
+      |""".stripMargin,
+    configureInFlag = { in => in.resolve("index.md").toString },
+    configureOutFlag = { out => out.resolve("out.md").toString }
+  )
+
+  checkCli(
+    "single-in-single-out-only",
+    """
+      |/index.md
+      |# Single file
+      |```scala mdoc
+      |println("one file")
+      |```
+      |/second.md
+      |```scala mdoc
+      |println("second file")
+      |```
+      |""".stripMargin,
+    """
+      |/out.md
+      |# Single file
+      |```scala
+      |println("one file")
+      |// one file
+      |```
+      |""".stripMargin,
+    configureInFlag = { in => in.resolve("index.md").toString },
+    configureOutFlag = { out => out.resolve("out.md").toString }
   )
 
 }