Splitted up modules doc section into contrib and external modules

2 files changed, 281 insertions, 285 deletions

diff --git a/docs/pages/10 - Thirdparty Modules.md b/docs/pages/10 - Thirdparty Modules.md
new file mode 100644
index 00000000..b98b9f67
--- /dev/null
+++ b/docs/pages/10 - Thirdparty Modules.md
@@ -0,0 +1,250 @@
+
+The modules (aka plugins) in this section are developed/maintained outside the mill git tree.
+
+Besides the documentation provided here, we urge you to consult the respective linked plugin documentation pages.
+The usage examples given here are most probably incomplete and sometimes outdated.
+
+If you develop or maintain a mill plugin, please create a [pull request](https://github.com/lihaoyi/mill/pulls) to get your plugin listed here.
+
+[comment]: # (Please keep list of plugins in alphabetical order)
+
+## DGraph
+
+Show transitive dependencies of your build in your browser.
+
+Project home: https://github.com/ajrnz/mill-dgraph
+
+### Quickstart
+
+```scala
+import $ivy.`com.github.ajrnz::mill-dgraph:0.2.0`
+```
+
+```sh
+sh> mill plugin.dgraph.browseDeps(proj)()
+```
+
+## Ensime
+
+Create an [.ensime](http://ensime.github.io/ "ensime") file for your build.
+
+Project home: https://github.com/yyadavalli/mill-ensime
+
+### Quickstart
+
+```scala
+import $ivy.`fun.valycorp::mill-ensime:0.0.1`
+```
+
+```sh
+sh> mill fun.valycorp.mill.GenEnsime/ensimeConfig
+```
+
+## Integration Testing Mill Plugins
+
+Integration testing for mill plugins.
+
+### Quickstart
+
+We assume, you have a mill plugin named `mill-demo`
+
+```scala
+// build.sc
+import mill._, mill.scalalib._
+object demo extends ScalaModule with PublishModule {
+  // ...
+}
+```
+
+Add an new test sub-project, e.g. `it`.
+
+```scala
+import $ivy.`de.tototec::de.tobiasroeser.mill.integrationtest:0.1.0`
+import de.tobiasroeser.mill.integrationtest._
+
+object it extends MillIntegrationTest {
+
+  def millTestVersion = "{exampleMillVersion}"
+
+  def pluginsUnderTest = Seq(demo)
+
+}
+```
+
+Your project should now look similar to this:
+
+```text
+.
++-- demo/
+|   +-- src/
+|
++-- it/
+    +-- src/
+        +-- 01-first-test/
+        |   +-- build.sc
+        |   +-- src/
+        |
+        +-- 02-second-test/
+            +-- build.sc
+```
+
+As the buildfiles `build.sc` in your test cases typically want to access the locally built plugin(s),
+the plugins publishes all plugins referenced under `pluginsUnderTest` to a temporary ivy repository, just before the test is executed.
+The mill version used in the integration test then used that temporary ivy repository.
+
+Instead of referring to your plugin with `import $ivy.'your::plugin:version'`,
+you can use the following line instead, which ensures you will use the correct locally build plugins.
+
+```scala
+// build.sc
+import $exec.plugins
+```
+
+Effectively, at execution time, this line gets replaced by the content of `plugins.sc`, a file which was generated just before the test started to execute.
+
+### Configuration and Targets
+
+The mill-integrationtest plugin provides the following targets.
+
+#### Mandatory configuration
+
+* `def millTestVersion: T[String]`
+  The mill version used for executing the test cases.
+  Used by `downloadMillTestVersion` to automatically download.
+
+* `def pluginsUnderTest: Seq[PublishModule]` -
+  The plugins used in the integration test.
+  You should at least add your plugin under test here.
+  You can also add additional libraries, e.g. those that assist you in the test result validation (e.g. a local test support project).
+  The defined modules will be published into a temporary ivy repository before the tests are executed.
+  In your test `build.sc` file, instead of the typical `import $ivy.` line,
+  you should use `import $exec.plugins` to include all plugins that are defined here.
+
+#### Optional configuration
+
+* `def sources: Sources` -
+  Locations where integration tests are located.
+  Each integration test is a sub-directory, containing a complete test mill project.
+
+* `def testCases: T[Seq[PathRef]]` -
+  The directories each representing a mill test case.
+  Derived from `sources`.
+
+* `def testTargets: T[Seq[String]]` -
+  The targets which are called to test the project.
+  Defaults to `verify`, which should implement test result validation.
+
+* `def downloadMillTestVersion: T[PathRef]` -
+  Download the mill version as defined by `millTestVersion`.
+  Override this, if you need to use a custom built mill version.
+  Returns the `PathRef` to the mill executable (must have the executable flag).
+
+#### Commands
+
+* `def test(): Command[Unit]` -
+  Run the integration tests.
+
+
+## JBake
+
+Create static sites/blogs with JBake.
+
+Plugin home: https://github.com/lefou/mill-jbake
+
+JBake home: https://jbake.org
+
+### Quickstart
+
+```scala
+// build.sc
+import mill._
+import $ivy.`de.tototec::de.tobiasroeser.mill.jbake:0.1.0`
+import de.tobiasroeser.mill.jbake._
+
+object site extends JBakeModule {
+
+  def jbakeVersion = "2.6.4"
+
+}
+```
+
+Generate the site:
+
+```sh
+bash> mill site.jbake
+```
+
+Start a local Web-Server on Port 8820 with the generated site:
+
+```sh
+bash> mill site.jbakeServe
+```
+
+
+## OSGi
+
+Produce OSGi Bundles with mill.
+
+Project home: https://github.com/lefou/mill-osgi
+
+### Quickstart
+
+```scala
+import mill._, mill.scalalib._
+import $ivy.`de.tototec::de.tobiasroeser.mill.osgi:0.0.5`
+import de.tobiasroeser.mill.osgi._
+
+object project extends ScalaModule with OsgiBundleModule {
+
+  def bundleSymbolicName = "com.example.project"
+
+  def osgiHeaders = T{ super.osgiHeaders().copy(
+    `Export-Package`   = Seq("com.example.api"),
+    `Bundle-Activator` = Some("com.example.internal.Activator")
+  )}
+
+  // other settings ...
+
+}
+```
+
+
+## PublishM2
+
+Mill plugin to publish artifacts into a local Maven repository.
+
+Project home: https://github.com/lefou/mill-publishM2
+
+### Quickstart
+
+Just mix-in the `PublishM2Module` into your project.
+`PublishM2Module` already extends mill's built-in `PublishModule`.
+
+File: `build.sc`
+```scala
+import mill._, scalalib._, publish._
+
+import $ivy.`de.tototec::de.tobiasroeser.mill.publishM2:0.0.1`
+import de.tobiasroeser.mill.publishM2._
+
+object project extends PublishModule with PublishM2Module {
+  // ...
+}
+```
+
+Publishing to default local Maven repository
+
+```bash
+> mill project.publishM2Local
+[40/40] project.publishM2Local
+Publishing to /home/user/.m2/repository
+```
+
+Publishing to custom local Maven repository
+
+```bash
+> mill project.publishM2Local /tmp/m2repo
+[40/40] project.publishM2Local
+Publishing to /tmp/m2repo
+```
+
diff --git a/docs/pages/9 - Contrib Modules.md b/docs/pages/9 - Contrib Modules.md
index 2f9085db..eca61be3 100644
--- a/docs/pages/9 - Contrib Modules.md
+++ b/docs/pages/9 - Contrib Modules.md
@@ -1,17 +1,18 @@
-## Contrib Modules
 
 The plugins in this section are developed/maintained in the mill git tree.
 
+When using one of these, you should make sure to use the versions that matches your mill version.
+
 [comment]: # (Please keep list of plugins in alphabetical order)
 
-### Bloop
+## Bloop
 
 This plugin generates [bloop](https://scalacenter.github.io/bloop/) configuration 
 from your build file, which lets you use the bloop CLI for compiling, and makes 
 your scala code editable in [Metals](https://scalameta.org/metals/)   
 
 
-#### Quickstart:
+### Quickstart
 ```scala
 // build.sc (or any other .sc file it depends on, including predef) 
 // Don't forget to replace VERSION
@@ -24,7 +25,7 @@ Then in your terminal :
 > mill mill.contrib.Bloop/install 
 ```
 
-#### Mix-in
+### Mix-in
 
 You can mix-in the `Bloop.Module` trait with any JavaModule to quickly access 
 the deserialised configuration for that particular module: 
@@ -40,7 +41,7 @@ object MyModule extends ScalaModule with Bloop.Module {
 }
 ``` 
 
-#### Note regarding metals: 
+### Note regarding metals 
 
 Generating the bloop config should be enough for metals to pick it up and for 
 features to start working in vscode (or the bunch of other editors metals supports). 
@@ -51,18 +52,18 @@ The generated bloop config references the semanticDB compiler plugin required by
 metals to function. If need be, the version of semanticDB can be overriden by 
 extending `mill.contrib.bloop.BloopImpl` in your own space. 
 
-#### Note regarding current mill support in bloop 
+### Note regarding current mill support in bloop 
 
 The mill-bloop integration currently present in the [bloop codebase](https://github.com/scalacenter/bloop/blob/master/integrations/mill-bloop/src/main/scala/bloop/integrations/mill/MillBloop.scala#L10)
 will be deprecated in favour of this implementation. 
 
-#### Caveats: 
+### Caveats
 
 At this time, only Java/ScalaModule are processed correctly. ScalaJS/ScalaNative integration will 
 be added in a near future. 
 
 
-### BuildInfo
+## BuildInfo
 
 Generate scala code from your buildfile.
 This plugin generates a single object containing information from your build.
@@ -87,7 +88,7 @@ object project extends BuildInfo {
 }
 ```
 
-#### Configuration options
+### Configuration options
 
 * `def buildInfoMembers: T[Map[String, String]]`
   The map containing all member names and values for the generated info object.
@@ -99,7 +100,7 @@ object project extends BuildInfo {
   The package name of the object.
   
   
-### Flyway
+## Flyway
 
 Enables you to configure and run [Flyway](https://flywaydb.org/) commands from your mill build file.
 The flyway module currently supports the most common flyway use cases with file based migrations.
@@ -143,7 +144,7 @@ mill foo.flywayMigrate
 > You should write some code to populate the settings for flyway instead.  
 > For example `def flywayPassword = T.input(T.ctx().env("FLYWAY_PASSWORD"))`
 
-### Play Framework
+## Play Framework
 
 This module adds basic Play Framework support to mill: 
 
@@ -156,7 +157,7 @@ This module adds basic Play Framework support to mill:
 There is no specific Play Java support, building a Play Java application will require a bit 
 of customization (mostly adding the proper dependencies).  
 
-#### Using the plugin
+### Using the plugin
 
 There are 2 base modules and 2 helper traits in this plugin, all of which can be found
  in `mill.playlib`.
@@ -178,7 +179,7 @@ directories at the top level alongside the `build.sc` file. This trait takes car
 * `RouterModule` allows you to use the Play router without the rest of the configuration (see 
 [Using the router module directly](#using-the-router-module-directly).)
 
-#### Using `PlayModule`
+### Using `PlayModule`
 
 In order to use the `PlayModule` for your application, you need to provide the scala, Play and 
 Twirl versions. You also need to define your own test object which extends the provided 
@@ -245,7 +246,7 @@ In order to have a working `start` command the following runtime dependency is a
 ivy"com.typesafe.play::play-akka-http-server:${playVersion()}"
 ```
 
-#### Using `PlayApiModule`
+### Using `PlayApiModule`
 
 The `PlayApiModule` trait behaves the same as the `PlayModule` trait but it won't process .scala
 .html files and you don't need to define the `twirlVersion:
@@ -266,12 +267,12 @@ object core extends PlayApiModule {
 }  
 ```
 
-#### Play configuration options
+### Play configuration options
 
 The Play modules themselves don't have specific configuration options at this point but the [router 
 module configuration options](#router-configuration-options) and the [Twirl module configuration options](#twirl-configuration-options) are applicable. 
 
-#### Additional play libraries
+### Additional play libraries
 
 The following helpers are available to provide additional Play Framework dependencies: 
 
@@ -306,7 +307,7 @@ object core extends PlayApiModule {
 }  
 ``` 
 
-#### Commands equivalence
+### Commands equivalence
 
 Mill commands are targets on a named build. For example if your build is called `core`:
 
@@ -322,7 +323,7 @@ starts a server in *PROD* mode which:
 command to get a runnable fat jar of the project. The packaging is slightly different but should 
 be find for a production deployment.
 
-#### Using `SingleModule`
+### Using `SingleModule`
 
 The `SingleModule` trait allows you to have the build descriptor at the same level as the source
  code on the filesystem. You can move from there to a multi-module build either by refactoring 
@@ -410,7 +411,7 @@ the layout becomes:
         └── controllers
 ```
 
-##### Using the router module directly
+#### Using the router module directly
 
 If you want to use the router module in a project which doesn't use the default Play layout, you 
 can mix-in the `mill.playlib.routesModule` trait directly when defining your module. Your app must
@@ -429,7 +430,7 @@ object app extends ScalaModule with RouterModule {
 }  
 ``` 
 
-###### Router Configuration options
+##### Router Configuration options
 
 * `def playVersion: T[String]` (mandatory) - The version of Play to use to compile the routes file.
 * `def scalaVersion: T[String]` - The scalaVersion in use in your project.
@@ -442,7 +443,7 @@ object app extends ScalaModule with RouterModule {
 * `def generatorType: RouteCompilerType = RouteCompilerType.InjectedGenerator` - The routes 
   compiler type, one of RouteCompilerType.InjectedGenerator or RouteCompilerType.StaticGenerator
   
-###### Details
+##### Details
 
 The following filesystem layout is expected by default:
 
@@ -483,7 +484,7 @@ object app extends ScalaModule with RouterModule {
 ``` 
 
 
-### ScalaPB
+## ScalaPB
 
 This module allows [ScalaPB](https://scalapb.github.io) to be used in Mill builds. ScalaPB is a [Protocol Buffers](https://developers.google.com/protocol-buffers/) compiler plugin that generates Scala case classes, encoders and decoders for protobuf messages.
 
@@ -514,7 +515,7 @@ example/
     resources/
 ```
 
-#### Configuration options
+### Configuration options
 
 * scalaPBVersion (mandatory) - The ScalaPB version `String` e.g. `"0.7.4"`
 
@@ -542,7 +543,7 @@ object example extends ScalaPBModule {
 }
 ```
 
-### TestNG
+## TestNG
 
 Provides support for [TestNG](https://testng.org/doc/index.html).
 
@@ -559,7 +560,7 @@ object project extends ScalaModule {
 }
 ```
 
-### Tut
+## Tut
 
 This module allows [Tut](https://tpolecat.github.io/tut) to be used in Mill builds. Tut is a documentation tool which compiles and evaluates Scala code in documentation files and provides various options for configuring how the results will be displayed in the compiled documentation.
 
@@ -598,7 +599,7 @@ In order to compile documentation we can execute the `tut` task in the module:
 sh> mill example.tut
 ```
 
-#### Configuration options
+### Configuration options
 
 * tutSourceDirectory - This task determines where documentation files must be placed in order to be compiled with Tut. By default this is the `tut` folder at the root of the module.
 
@@ -618,7 +619,7 @@ sh> mill example.tut
 
 * tutPluginJars - A task which performs the dependency resolution for the scalac plugins to be used with Tut.
 
-### Twirl
+## Twirl
 
 Twirl templates support.
 
@@ -637,7 +638,7 @@ object app extends ScalaModule with TwirlModule {
 } 
 ``` 
 
-#### Twirl configuration options
+### Twirl configuration options
 
 * `def twirlVersion: T[String]` (mandatory) - the version of the twirl compiler to use, like "1.3.15"
 * `def twirlAdditionalImports: Seq[String] = Nil` - the additional imports that will be added by twirl compiler to the top of all templates
@@ -645,7 +646,7 @@ object app extends ScalaModule with TwirlModule {
 * `def twirlCodec = Codec(Properties.sourceEncoding)` - the codec used to generate the files (the default is the same sbt plugin uses) 
 * `def twirlInclusiveDot: Boolean = false`  
   
-#### Details
+### Details
 
 The following filesystem layout is expected:
 
@@ -719,261 +720,6 @@ Seq(
 
 These imports will always be added to every template.  You don't need to list them if you override `twirlAdditionalImports`.
 
-#### Example
+### Example
 There's an [example project](https://github.com/lihaoyi/cask/tree/master/example/twirl)
 
-
-
-## Thirdparty Mill Plugins
-
-The plugins in this section are developed/maintained outside the mill git tree.
-
-Besides the documentation provided here, we urge you to consult the respective linked plugin documentation pages.
-The usage examples given here are most probably outdated and incomplete.
-
-If you develop or maintain a mill plugin, please create a [pull request](https://github.com/lihaoyi/mill/pulls) to get your plugin listed here.
-
-[comment]: # (Please keep list of plugins in alphabetical order)
-
-
-
-### DGraph
-
-Show transitive dependencies of your build in your browser.
-
-Project home: https://github.com/ajrnz/mill-dgraph
-
-#### Quickstart
-
-```scala
-import $ivy.`com.github.ajrnz::mill-dgraph:0.2.0`
-```
-
-```sh
-sh> mill plugin.dgraph.browseDeps(proj)()
-```
-
-### Ensime
-
-Create an [.ensime](http://ensime.github.io/ "ensime") file for your build.
-
-Project home: https://github.com/yyadavalli/mill-ensime
-
-#### Quickstart
-
-```scala
-import $ivy.`fun.valycorp::mill-ensime:0.0.1`
-```
-
-```sh
-sh> mill fun.valycorp.mill.GenEnsime/ensimeConfig
-```
-
-### Integration Testing Mill Plugins
-
-Integration testing for mill plugins.
-
-#### Quickstart
-
-We assume, you have a mill plugin named `mill-demo`
-
-```scala
-// build.sc
-import mill._, mill.scalalib._
-object demo extends ScalaModule with PublishModule {
-  // ...
-}
-```
-
-Add an new test sub-project, e.g. `it`.
-
-```scala
-import $ivy.`de.tototec::de.tobiasroeser.mill.integrationtest:0.1.0`
-import de.tobiasroeser.mill.integrationtest._
-
-object it extends MillIntegrationTest {
-
-  def millTestVersion = "{exampleMillVersion}"
-
-  def pluginsUnderTest = Seq(demo)
-
-}
-```
-
-Your project should now look similar to this:
-
-```text
-.
-+-- demo/
-|   +-- src/
-|
-+-- it/
-    +-- src/
-        +-- 01-first-test/
-        |   +-- build.sc
-        |   +-- src/
-        |
-        +-- 02-second-test/
-            +-- build.sc
-```
-
-As the buildfiles `build.sc` in your test cases typically want to access the locally built plugin(s),
-the plugins publishes all plugins referenced under `pluginsUnderTest` to a temporary ivy repository, just before the test is executed.
-The mill version used in the integration test then used that temporary ivy repository.
-
-Instead of referring to your plugin with `import $ivy.'your::plugin:version'`,
-you can use the following line instead, which ensures you will use the correct locally build plugins.
-
-```scala
-// build.sc
-import $exec.plugins
-```
-
-Effectively, at execution time, this line gets replaced by the content of `plugins.sc`, a file which was generated just before the test started to execute.
-
-#### Configuration and Targets
-
-The mill-integrationtest plugin provides the following targets.
-
-##### Mandatory configuration
-
-* `def millTestVersion: T[String]`
-  The mill version used for executing the test cases.
-  Used by `downloadMillTestVersion` to automatically download.
-
-* `def pluginsUnderTest: Seq[PublishModule]` -
-  The plugins used in the integration test.
-  You should at least add your plugin under test here.
-  You can also add additional libraries, e.g. those that assist you in the test result validation (e.g. a local test support project).
-  The defined modules will be published into a temporary ivy repository before the tests are executed.
-  In your test `build.sc` file, instead of the typical `import $ivy.` line,
-  you should use `import $exec.plugins` to include all plugins that are defined here.
-
-##### Optional configuration
-
-* `def sources: Sources` -
-  Locations where integration tests are located.
-  Each integration test is a sub-directory, containing a complete test mill project.
-
-* `def testCases: T[Seq[PathRef]]` -
-  The directories each representing a mill test case.
-  Derived from `sources`.
-
-* `def testTargets: T[Seq[String]]` -
-  The targets which are called to test the project.
-  Defaults to `verify`, which should implement test result validation.
-
-* `def downloadMillTestVersion: T[PathRef]` -
-  Download the mill version as defined by `millTestVersion`.
-  Override this, if you need to use a custom built mill version.
-  Returns the `PathRef` to the mill executable (must have the executable flag).
-
-##### Commands
-
-* `def test(): Command[Unit]` -
-  Run the integration tests.
-
-
-### JBake
-
-Create static sites/blogs with JBake.
-
-Plugin home: https://github.com/lefou/mill-jbake
-
-JBake home: https://jbake.org
-
-#### Quickstart
-
-```scala
-// build.sc
-import mill._
-import $ivy.`de.tototec::de.tobiasroeser.mill.jbake:0.1.0`
-import de.tobiasroeser.mill.jbake._
-
-object site extends JBakeModule {
-
-  def jbakeVersion = "2.6.4"
-
-}
-```
-
-Generate the site:
-
-```sh
-bash> mill site.jbake
-```
-
-Start a local Web-Server on Port 8820 with the generated site:
-
-```sh
-bash> mill site.jbakeServe
-```
-
-
-### OSGi
-
-Produce OSGi Bundles with mill.
-
-Project home: https://github.com/lefou/mill-osgi
-
-#### Quickstart
-
-```scala
-import mill._, mill.scalalib._
-import $ivy.`de.tototec::de.tobiasroeser.mill.osgi:0.0.5`
-import de.tobiasroeser.mill.osgi._
-
-object project extends ScalaModule with OsgiBundleModule {
-
-  def bundleSymbolicName = "com.example.project"
-
-  def osgiHeaders = T{ super.osgiHeaders().copy(
-    `Export-Package`   = Seq("com.example.api"),
-    `Bundle-Activator` = Some("com.example.internal.Activator")
-  )}
-
-  // other settings ...
-
-}
-```
-
-
-### PublishM2
-
-Mill plugin to publish artifacts into a local Maven repository.
-
-Project home: https://github.com/lefou/mill-publishM2
-
-#### Quickstart
-
-Just mix-in the `PublishM2Module` into your project.
-`PublishM2Module` already extends mill's built-in `PublishModule`.
-
-File: `build.sc`
-```scala
-import mill._, scalalib._, publish._
-
-import $ivy.`de.tototec::de.tobiasroeser.mill.publishM2:0.0.1`
-import de.tobiasroeser.mill.publishM2._
-
-object project extends PublishModule with PublishM2Module {
-  // ...
-}
-```
-
-Publishing to default local Maven repository
-
-```bash
-> mill project.publishM2Local
-[40/40] project.publishM2Local
-Publishing to /home/user/.m2/repository
-```
-
-Publishing to custom local Maven repository
-
-```bash
-> mill project.publishM2Local /tmp/m2repo
-[40/40] project.publishM2Local
-Publishing to /tmp/m2repo
-```
-