Merge pull request #293 from 47deg/add-mdoc-capabilities

Add support to use mdoc

.travis.yml

@@ -8,9 +8,6 @@ matrix:
     - scala: 2.12.6
       env:
         - SBT_VERSION=1.1.6
-    - scala: 2.10.6
-      env:
-        - SBT_VERSION=0.13.16
 
 before_install:
   - if [ "$TRAVIS_BRANCH" = "master" -a "$TRAVIS_PULL_REQUEST" = "false" ]; then

docs/src/main/resources/microsite/data/menu.yml

@@ -5,6 +5,9 @@ options:
   - title: Configuring the Microsite
     url: docs/settings.html
 
+  - title: Typechecked Snippets
+    url: docs/typechecked-snippets.html
+
   - title: Layouts
     url: docs/layouts.html
 

docs/src/main/tut/docs/index.md

@@ -8,7 +8,7 @@ title: Getting Started
 * [sbt](http://www.scala-sbt.org/) 0.13.8+
 * [jekyll](https://jekyllrb.com/) 3.2.1+
 
-To satisfy the `jekyll` prerequisite, here are a few hints for local and travis environments.
+Here are a few hints for local and travis environments to satisfy the `jekyll` requirement.
 
 ## Local Environment
 
@@ -26,16 +26,16 @@ gem install jekyll
 
 ## Continuous Integration - Travis
 
-If you have enabled [Travis](https://travis-ci.org/) for your project, you might have to tweak some parts of your `.travis.yml` file:
+If you have [Travis](https://travis-ci.org/) enabled for your project, you might have to tweak parts of your `.travis.yml` file:
 
-Potentially, your project is a Scala project (`language: scala`), therefore you need to add the bundle gems vendor path in the `PATH` environment variable:
+If you're working on a Scala project (`language: scala`), you need to add the bundle gems vendor path in the `PATH` environment variable:
 
 ```bash
 before_install:
  - export PATH=${PATH}:./vendor/bundle
 ```
 
-This is needed in order to install and be able to use the `jekyll` gem from other parts of your travis descriptor file. Once we have the `/vendor/bundle` path in the Travis `PATH` env variable, we have to install the gem in the `install` travis section:
+This is needed in order to install and use the `jekyll` gem from other parts of your travis descriptor file. Once we have the `/vendor/bundle` path in the Travis `PATH` env variable, we have to install the gem in the `install` travis section:
 
 ```bash
 install:
@@ -47,7 +47,7 @@ install:
 
 # Set it up in your Project
 
-To begin, add the following lines to the `project/plugins.sbt` file within your project or sbt module where you want to use the `sbt-microsites` plugin. Depending on the version, you might want to use:
+To begin, add the following lines to the `project/plugins.sbt` file within your project or the sbt module where you want to use the `sbt-microsites` plugin. Depending on the version, you might want to use:
 
 Latest release:
 
@@ -63,3 +63,10 @@ Finally, to enable the plugin, add this to your `build.sbt` file:
 ```bash
 enablePlugins(MicrositesPlugin)
 ```
+
+# Write your documentation `.md` files
+
+Your docs can be placed wherever you want in your project since there are sbt settings to point to the sources of your microsite, however the plugin expects to find the sources where both [**tut**](https://github.com/tpolecat/tut) and [**mdoc**](https://github.com/scalameta/mdoc) have defined by default. They are:
+
+- Tut: `src/main/tut/`
+- mdoc: `docs/`

docs/src/main/tut/docs/publish-with-travis.md

@@ -88,7 +88,7 @@ This is the `.travis.yml` in `sbt-microsite` project:
 ```
 language: scala
 scala:
-- 2.10.6
+- 2.12.6
 jdk:
 - oraclejdk8
 before_install:

docs/src/main/tut/docs/settings.md

@@ -344,3 +344,10 @@ compiles the site.  **The strings are passed in unsanitized to the templating en
 ```
 micrositeEditButton := Some(MicrositeEditButton("Improve this Page", "/edit/master/docs/src/main/tut/{{ page.path }}"))
 ```
+
+- `micrositeCompilingDocsTool`: Choose between compiling code snippets with [**tut**](https://github.com/tpolecat/tut) or [**mdoc**](https://github.com/scalameta/mdoc). By default, it's set to `tut` in order to preserve compatibility with previous versions of your markdown files. But `mdoc` and all the features it includes is now also supported.
+
+```scala
+micrositeCompilingDocsTool := "mdoc"
+```
+If you are interested in learning where to place the markdown files according to the compilation tool chosen, please take a look at the [Typechecked Snippets](typechecked-snippets.html) section.

docs/src/main/tut/docs/typechecked-snippets.md

@@ -0,0 +1,49 @@
+---
+layout: docs
+title: Typechecked Snippets
+---
+
+# Typechecked Snippets
+
+As has been mentioned a couple of times throughout this tutorial, this plugin supports the compilation of Scala code written in markdown files. This process is now being delegated on two different sbt plugins: [**tut**](https://github.com/tpolecat/tut) and [**mdoc**](https://github.com/scalameta/mdoc).
+
+## Tut
+
+Tut is the option by default, so no special action is required from your side, apart from following the guides defined in its [microsite](http://tpolecat.github.io/tut/). Some recommendations:
+
+- Add your markdown files in this path by default: `src/main/tut/`.
+- If you want to place your documments in a different path, just set the sbt property `tutSourceDirectory := your-path` being _your-path_ a `SettingKey[File]`.
+- Mark the snippets that you want to compile, following this convention: **_```tut_** or any of its [modifiers](http://tpolecat.github.io/tut//modifiers.html)
+
+
+## mdoc
+
+This feature has been recently added and includes some amazing features that are [explained](https://scalameta.org/mdoc/) very well. Here is some advice for using this in your microsite:
+
+- Add your markdown files in this path by default: `docs/`.
+- Set this property accordingly: `micrositeCompilingDocsTool := "mdoc"`
+- If you want to place your documments in a different path, just set the sbt property `mdocIn := your-path` being _your-path_ a `SettingKey[File]`.
+- Mark the snippets that you want to compile, following this convention: **_```scala mdoc_** or any of its [modifiers](https://scalameta.org/mdoc/docs/modifiers.html)
+
+## Migrating from tut to mdoc
+
+You can migrate your microsite from _tut_ to _mdoc_ in 3 smooth steps:
+
+- Set this property accordingly: `micrositeCompilingDocsTool := "mdoc"`
+- Set the property `mdocIn := tutSourceDirectory`, thus we are setting the source for mdoc as it used to be for tut.
+- Replace **_tut_** with **_scala mdoc_** in the snippets modifiers following this table of compatibilities
+
+| tut                | mdoc                                                  |
+| ------------------ | ----------------------------------------------------- |
+| `:fail`            | `:fail` for compile error, `:crash` for runtime error |
+| `:nofail`          | n/a                                                   |
+| `:silent`          | `:silent`                                             |
+| `:plain`           | n/a                                                   |
+| `:invisible`       | `:invisible`                                          |
+| `:book`            | can be removed, mdoc uses book mode by default        |
+| `:evaluated`       | n/a                                                   |
+| `:passthrough`     | `:passthrough`                                        |
+| `:decorate(param)` | n/a                                                   |
+| `:reset`           | `:reset`                                              |
+
+There is also a [script](https://github.com/scalameta/mdoc/blob/master/bin/migrate-tut.sh) that does the replacement for you.

project/ProjectPlugin.scala

@@ -48,6 +48,10 @@ object ProjectPlugin extends AutoPlugin {
             "org.tpolecat" % "tut-plugin" % tutPluginVersion,
             sbtBinaryVersionValue,
             scalaBinaryVersionValue),
+          Defaults.sbtPluginExtra(
+            "org.scalameta" % "sbt-mdoc" % "1.2.3",
+            sbtBinaryVersionValue,
+            scalaBinaryVersionValue),
           "com.sksamuel.scrimage" %% "scrimage-core" % scrimageVersion
         )
       }

src/main/scala/microsites/MicrositeKeys.scala

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016-2018 47 Degrees, LLC. <http://www.47deg.com>
+ * Copyright 2016-2019 47 Degrees, LLC. <http://www.47deg.com>
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -29,6 +29,7 @@ import sbt._
 import sbt.complete.DefaultParsers.OptNotSpace
 import sbtorgpolicies.github.GitHubOps
 import tut.TutPlugin.autoImport._
+import mdoc.MdocPlugin.autoImport._
 
 trait MicrositeKeys {
 
@@ -51,6 +52,9 @@ trait MicrositeKeys {
   }
 
   val makeMicrosite: TaskKey[Unit] = taskKey[Unit]("Main Task to build a Microsite")
+  val makeTut: TaskKey[Unit]       = taskKey[Unit]("Sequential tasks to compile tut and move the result")
+  val makeMdoc: TaskKey[Unit] =
+    taskKey[Unit]("Sequential tasks to compile mdoc and move the result")
   val publishMicrosite: TaskKey[Unit] =
     taskKey[Unit]("Task helper that wraps the `publishMicrositeCommand`.")
   val microsite: TaskKey[Seq[File]] = taskKey[Seq[File]]("Create microsite files")
@@ -159,6 +163,9 @@ trait MicrositeKeys {
     settingKey[Option[MicrositeEditButton]](
       "Optional. Add a button in DocsLayout pages that links to the file in the repository."
     )
+
+  val micrositeCompilingDocsTool =
+    settingKey[String]("Choose between compiling code snippets with tut or mdoc")
 }
 
 object MicrositeKeys extends MicrositeKeys
@@ -261,8 +268,7 @@ trait MicrositeAutoImportSettings extends MicrositeKeys {
 
   lazy val micrositeTasksSettings = Seq(
     microsite := micrositeHelper.value.createResources(
-      resourceManagedDir = (resourceManaged in Compile).value,
-      tutSourceDirectory = (tutSourceDirectory in Compile).value),
+      resourceManagedDir = (resourceManaged in Compile).value),
     micrositeConfig := micrositeHelper.value
       .copyConfigurationFile((sourceDirectory in Jekyll).value, siteDirectory.value),
     micrositeMakeExtraMdFiles := micrositeHelper.value.buildAdditionalMd(),
@@ -276,17 +282,19 @@ trait MicrositeAutoImportSettings extends MicrositeKeys {
       val re    = tutNameFilter.value.pattern.toString
       _root_.tut.TutPlugin.tutOne(streams.value, r, in, out, cp, opts, pOpts, re).map(_._1)
     },
-    makeMicrosite := {
-      Def
-        .sequential(
-          microsite,
-          tut,
-          micrositeTutExtraMdFiles,
-          makeSite,
-          micrositeConfig
-        )
-        .value
-    },
+    makeTut := {
+      Def.sequential(microsite, tut, micrositeTutExtraMdFiles, makeSite, micrositeConfig)
+    }.value,
+    makeMdoc := {
+      Def.sequential(microsite, mdoc.toTask(""), makeSite, micrositeConfig)
+    }.value,
+    makeMicrosite := Def.taskDyn {
+      micrositeCompilingDocsTool.value match {
+        case "tut"  => Def.task(makeTut.value)
+        case "mdoc" => Def.task(makeMdoc.value)
+        case _      => Def.task(streams.value.log.error("Invalid value for micrositeCompilingDocsTool"))
+      }
+    }.value,
     publishMicrosite := Def.taskDyn {
       val siteDir: File                 = (target in makeSite).value
       val noJekyll: Boolean             = ghpagesNoJekyll.value

src/main/scala/microsites/MicrositesPlugin.scala

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016-2018 47 Degrees, LLC. <http://www.47deg.com>
+ * Copyright 2016-2019 47 Degrees, LLC. <http://www.47deg.com>
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -25,6 +25,8 @@ import sbt._
 import sbt.plugins.IvyPlugin
 import tut.TutPlugin
 import tut.TutPlugin.autoImport._
+import mdoc.MdocPlugin
+import mdoc.MdocPlugin.autoImport._
 
 object MicrositesPlugin extends AutoPlugin {
 
@@ -33,7 +35,8 @@ object MicrositesPlugin extends AutoPlugin {
   import MicrositesPlugin.autoImport._
   import com.typesafe.sbt.site.jekyll.JekyllPlugin.autoImport._
 
-  override def requires: Plugins = IvyPlugin && TutPlugin && JekyllPlugin && GhpagesPlugin
+  override def requires: Plugins =
+    IvyPlugin && MdocPlugin && TutPlugin && JekyllPlugin && GhpagesPlugin
 
   override def trigger: PluginTrigger = allRequirements
 
@@ -45,7 +48,9 @@ object MicrositesPlugin extends AutoPlugin {
         mappings in Jekyll ++= micrositeHelper.value.directory("src/main/resources/microsite"),
         sourceDirectory in Jekyll := resourceManaged.value / "main" / "jekyll",
         tutSourceDirectory := sourceDirectory.value / "main" / "tut",
-        tutTargetDirectory := resourceManaged.value / "main" / "jekyll"
+        tutTargetDirectory := resourceManaged.value / "main" / "jekyll",
+        mdocIn := baseDirectory.in(ThisBuild).value / "docs",
+        mdocOut := resourceManaged.value / "main" / "jekyll",
       )
 
   lazy val micrositeDefaultSettings = Seq(
@@ -111,6 +116,7 @@ object MicrositesPlugin extends AutoPlugin {
     micrositeFooterText := Some(layouts.Layout.footer.toString),
     micrositeEditButton := None,
     micrositeGithubLinks := true,
+    micrositeCompilingDocsTool := "tut",
     includeFilter in makeSite := "*.html" | "*.css" | "*.png" | "*.jpg" | "*.jpeg" | "*.gif" | "*.js" | "*.swf" | "*.md" | "*.webm" | "*.ico" | "CNAME" | "*.yml" | "*.svg" | "*.json",
     includeFilter in Jekyll := (includeFilter in makeSite).value,
     commands ++= Seq(publishMicrositeCommand)

src/main/scala/microsites/layouts/DocsLayout.scala

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016-2018 47 Degrees, LLC. <http://www.47deg.com>
+ * Copyright 2016-2019 47 Degrees, LLC. <http://www.47deg.com>
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

src/main/scala/microsites/layouts/HomeLayout.scala

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016-2018 47 Degrees, LLC. <http://www.47deg.com>
+ * Copyright 2016-2019 47 Degrees, LLC. <http://www.47deg.com>
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

src/main/scala/microsites/layouts/Layout.scala

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016-2018 47 Degrees, LLC. <http://www.47deg.com>
+ * Copyright 2016-2019 47 Degrees, LLC. <http://www.47deg.com>
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

src/main/scala/microsites/layouts/MenuPartialLayout.scala

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016-2018 47 Degrees, LLC. <http://www.47deg.com>
+ * Copyright 2016-2019 47 Degrees, LLC. <http://www.47deg.com>
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

src/main/scala/microsites/layouts/PageLayout.scala

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016-2018 47 Degrees, LLC. <http://www.47deg.com>
+ * Copyright 2016-2019 47 Degrees, LLC. <http://www.47deg.com>
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

src/main/scala/microsites/microsites.scala

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016-2018 47 Degrees, LLC. <http://www.47deg.com>
+ * Copyright 2016-2019 47 Degrees, LLC. <http://www.47deg.com>
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

src/main/scala/microsites/util/BuildHelper.scala

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016-2018 47 Degrees, LLC. <http://www.47deg.com>
+ * Copyright 2016-2019 47 Degrees, LLC. <http://www.47deg.com>
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.