atooni/mill-mdoc

Simple MDoc runner for mill

Simple MDoc runner for Mill

This plugin provides a mill module that allows to execute Scala MDoc from within a mill build. Scala MDoc simply compiles properly marked Scala snippets in plain md files and optionally runs them through an interpreter, augmenting the code with the interpreter output.

If the code can't be compiled, mdoc throws an error and the build fails.

Using mdoc, developers can ensure the correctness of their code samples.

The mill plugin is simply a wrapper around the main class, translating common project parameters into arguments for mdocs Main class.

Further, the mill plugin can run the compilation in watch mode, redirecting the md files to a different location. For example, if that location points to an input directory for md files used by a static content generator such as Docusaurus 2 and that generator is started in watch mode as well, the developer can work on the md files and code snippets and immediately observe the results.

Parameters

scalaMdocVersion

A string parameter denoting the Scala MDoc version used. This is currently set to 2.2.24 by default.

scalaMdocDep

An Ivy dependency pointing to Scala MDoc. This is by default derived from scalaMdocVersion as ivy"org.scalameta::mdoc:${scalaMdocVersion()}"

watchedMDocsDestination

An optional Path parameter pointing to a directory where compiled md files should be saved in watch mode. This is set to None as a default.

Using mdocWatch without setting this parameter won't work.

mdocSources

The sources where the input md files are kept.

Targets

mdoc

Run mill -i __.mdoc or any other mdoc task to compile the Scala code within the source md files and produce new md files in the task's destination directory.

mdocWatch

Run mill -i __.mdocWatch to run mdoc in watch mode. This will block the shell the command is run in until the command is interrupted. Normally this is used in combination with a static content generator in watch mode.

Example usage

  //... Other imports if requried 

  // Add simple mdoc support for mill
  import $ivy.`de.wayofquality.blended::de.wayofquality.blended.mill.mdoc::0.0.1-1-fdff74`
  import de.wayofquality.mill.mdoc.MDocModule

  object site extends DocusaurusModule with MDocModule {
    // Set the Scala version (required to invoke the proper compiler)
    override def scalaVersion = T(Deps.scalaVersion)
    // The md inputs live in the "docs" folder of the project 
    override def mdocSources = T.sources{ T.workspace / "docs" }
    override def docusaurusSources = T.sources(
      T.workspace / "website"
    )

    // If we are running docusaurus in watch mode we want to replace compiled 
    // mdoc files on the fly - this will NOT build md files for the site
    // Hence we must use `mdoc` once we finished editing.
    override def watchedMDocsDestination: T[Option[Path]] = T(Some(docusaurusBuild().path / "docs"))

    // This is where docusaurus will find the compiled mdocs to BUILD the site
    override def compiledMdocs: Sources = T.sources(mdoc().path)
}

mill-mdoc's Issues

License file?

Hi, I just realized build.sc declares the license, but the repo doesn't have one in the root directory.

mill-mdoc/build.sc

Line 77 in 2f8b5e3

licenses = Seq(License.`Apache-2.0`),

Could you add this just for clarification please?

Classpath problem in MDocModule.mdoc

While trying to use this module I got an error in the imports. After some some searching I noticed that MDoc's --classpath is not being used in the call to Jvm.runLocal. More concretely the command line arguments should be changed.

Here is my working version that I use as an override:

  override def mdoc : T[PathRef] = T {
  
    val cp = runClasspath().map(_.path)
    val separator = java.io.File.pathSeparatorChar
  
    val dir = T.dest.toIO.getAbsolutePath
    val dirParams = mdocSources().map(pr => Seq(
        "--classpath", cp.mkString(s"$separator"),
        "--in", pr.path.toIO.getAbsolutePath, 
        "--out",  dir)
      ).iterator.flatten.toSeq
  
    Jvm.runLocal("mdoc.Main", cp, dirParams)
  
    PathRef(T.dest)
  }

Two additional notes:

• The original code uses a s"--in" but string interpolation is not used
• We do not really need to add all of the applications classpath via the cp parameter. I think here we should just add MDoc and its dependencies.

Error: java.lang.ClassNotFoundException: mdoc.Main

I have set-up a simple build.sc to use mdoc but am getting the error.

Compiling /home/hmf/VSCodeProjects/stensorflow/build.sc
[40/40] tutorial.mdoc 
1 targets failed
tutorial.mdoc java.lang.ClassNotFoundException: mdoc.Main
    java.base/java.net.URLClassLoader.findClass(URLClassLoader.java:445)
    mill.api.ClassLoader$$anon$1.findClass(ClassLoader.scala:47)
    java.base/java.lang.ClassLoader.loadClass(ClassLoader.java:587)
    java.base/java.lang.ClassLoader.loadClass(ClassLoader.java:520)
    mill.modules.Jvm$.getMainMethod(Jvm.scala:268)
    mill.modules.Jvm$.$anonfun$runLocal$1(Jvm.scala:262)
    mill.util.Jvm$.inprocess(Jvm.scala:30)
    mill.modules.Jvm$.inprocess(Jvm.scala:288)
    mill.modules.Jvm$.runLocal(Jvm.scala:256)
    de.wayofquality.mill.mdoc.MDocModule.$anonfun$mdoc$2(MDocModule.scala:23)
    mill.define.Task$TraverseCtx.evaluate(Task.scala:380)

I am using:

import mill._
import mill.api.Loose
import mill.define.{Target, Task}
import scalalib._
import coursier.core.Resolution
import java.io.File

// Import JavaCPP to get host OS name
import $ivy.`org.bytedeco:javacpp:1.5.7`

// Add simple mdoc support for mill
// https://mvnrepository.com/artifact/org.scalameta/mdoc
import $ivy.`org.scalameta::mdoc:2.3.3`
//import $ivy.`org.scalameta::mdoc:2.2.4`
import $ivy.`de.wayofquality.blended::de.wayofquality.blended.mill.mdoc::0.0.4-2-2f8b5e`
import de.wayofquality.mill.mdoc.MDocModule

val ScalaVersion         = "3.2.1-RC2" // "3.1.3"
val mUnitVersion         = "1.0.0-M6" 
val javaCPPVersion       = "1.5.7"
val tensorflowVersion    = "0.4.1" // TF:2.7.1

object tutorial extends ScalaModule with MDocModule {
  // Also used by mill-mdoc
  override def scalaVersion = T{ ScalaVersion }

  override def javacOptions = T{ Seq("-source", "17", "-target", "17", "-Xlint") }
  override def scalacOptions = T{ Seq("-deprecation", "-feature") }

  // mdoc
  override def scalaMdocVersion = "2.3.3" // "2.2.4"
  override def mdocSources = T.sources{ T.workspace / "docs" }  

  def javaCPPPlatform = T{ org.bytedeco.javacpp.Loader.Detector.getPlatform }

  override def ivyDeps = Agg(
      ivy"org.tensorflow:tensorflow-core-api:${tensorflowVersion}",
      ivy"org.tensorflow:tensorflow-core-api:${tensorflowVersion};classifier=${javaCPPPlatform()}"
  )

  object test extends Tests with TestModule.Munit {

    def ivyDeps = Agg(ivyMunit)
    def testFramework = ivyMunitInterface
  }
}

I have tried versions of mdoc "2.3.3" and the examples "2.2.4" and get the same error. I found this. Can this be an issue with using Scala 3.x? I did find that SBT now works with the version 3 compiler.

EDIT: I also tried it with and without the line

import $ivy.`org.scalameta::mdoc:2.3.3`

but got the same result.

I also looked at the source code and googled and cannot figure out were/how mdoc can set the compiler version. Where is this done here?

TIA

MDoc Scala JS support?

I conclude this isn't supported right now?

Missing `mill-plugin` tag

All mill plugin have that tag to allow easy search on Github via https://github.com/search?q=mill-plugin