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

docs/installation.md

@@ -151,6 +151,14 @@ contained, by default the `docs/` directory is used.
 +  --in mydocs
 ```
 
+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
+```
+
 Use `--site.VARIABLE=value` to add site variables that can be referenced from
 markdown as `@@VARIABLE@`.
 
@@ -159,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

@@ -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 indidivual file"
       )
     val mdocExtraArguments =
       settingKey[Seq[String]](

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

@@ -121,7 +121,12 @@ final class MainOps(
   }
 
   def generateCompleteSite(): Exit = {
-    val files = IO.inputFiles(settings)
+    val isFile = Files.isRegularFile(settings.in.toNIO)
+    val files = if (isFile) {
+      settings.toInputFile(settings.in).toList
+    } else {
+      IO.inputFiles(settings)
+    }
     val timer = new Timer()
     val n = files.length
     compilingFiles(n)

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

@@ -35,13 +35,17 @@ class Section(val name: String) extends StaticAnnotation
 case class Settings(
     @Section("Common options")
     @Description(
-      "The input directory containing markdown and other documentation sources. " +
-        "Markdown files will be processed by mdoc while other files will be copied " +
-        "verbatim to the output directory."
+      "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."
     )
     @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,17 +165,27 @@ case class Settings(
   def isFileWatching: Boolean = watch && !check
 
   def toInputFile(infile: AbsolutePath): Option[InputFile] = {
-    val relpath = infile.toRelative(in)
-    if (isIncluded(relpath)) {
-      val outfile = out.resolve(relpath)
-      Some(InputFile(relpath, infile, outfile))
+    val relativeIn = if (infile == in) {
+      RelativePath(in.toNIO.getFileName.toString)
+    } else {
+      infile.toRelative(in)
+    }
+    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)
@@ -181,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)
@@ -198,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,6 +19,8 @@ abstract class BaseCliSuite extends FunSuite {
       expected: String,
       extraArgs: Array[String] = Array.empty,
       setup: CliFixture => Unit = _ => (),
+      configureInFlag: AbsolutePath => String = _.toString,
+      configureOutFlag: Path => String = _.toString,
       expectedExitCode: Int = 0,
       onStdout: String => Unit = _ => ()
   ): Unit = {
@@ -29,9 +31,9 @@ abstract class BaseCliSuite extends FunSuite {
       setup(CliFixture(in.toNIO, out))
       val args = Array[String](
         "--in",
-        in.toString,
+        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

@@ -2,6 +2,8 @@ package tests.cli
 
 import java.nio.file.Files
 import mdoc.internal.BuildInfo
+import scala.meta.io.AbsolutePath
+import java.nio.file.Paths
 
 class CliSuite extends BaseCliSuite {
 
@@ -187,4 +189,94 @@ class CliSuite extends BaseCliSuite {
       |""".stripMargin
   )
 
+  checkCli(
+    "single-in",
+    """
+      |/index.md
+      |# Single file
+      |```scala mdoc
+      |println("one file")
+      |```
+      |""".stripMargin,
+    """
+      |/index.md
+      |# Single file
+      |```scala
+      |println("one file")
+      |// one file
+      |```
+      |""".stripMargin,
+    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 }
+  )
+
 }

website/package.json

@@ -9,6 +9,6 @@
     "rename-version": "docusaurus-rename-version"
   },
   "devDependencies": {
-    "docusaurus": "1.6.2"
+    "docusaurus": "1.14.4"
   }
 }