Integrate new kotlin examples into docsite (#3592)

Apart from adding `.adoc` pages for all the kotlin examples
#3585
#3589
#3555 and the palantir java
format example from
https://github.com/com-lihaoyi/mill/pulls?page=2&q=is%3Apr+is%3Aclosed,
I moved some docs around: the first few things under `Foo Example
Builds` really belong under `Foo Module Configuration`, the
`external/libraries/` folder should be in `depth/libraries/`

The test for `Custom Main Argument Parsers` seems to have bitrotted
since it was implemented, and it accidentally wasn't running in the test
suite before so we didn't notice. For now just disabling that test and
we can fix it later

ci/test-mill-dev.sh

@@ -2,7 +2,7 @@
 
 set -eux
 
-EXAMPLE=example/scalalib/builds/9-realistic
+EXAMPLE=example/scalalib/builds/4-realistic
 
 rm -rf $EXAMPLE/out
 

ci/test-mill-release.sh

@@ -5,7 +5,7 @@ set -eux
 # Build Mill
 ./mill -i dist.assembly
 
-EXAMPLE=example/scalalib/builds/9-realistic
+EXAMPLE=example/scalalib/builds/4-realistic
 
 rm -rf $EXAMPLE/out
 

docs/modules/ROOT/nav.adoc

@@ -26,6 +26,11 @@
 .xref:Kotlin_Intro_to_Mill.adoc[]
 * xref:Kotlin_Installation_IDE_Support.adoc[]
 * xref:Kotlin_Builtin_Commands.adoc[]
+* xref:Kotlin_Module_Config.adoc[]
+* xref:Kotlin_Build_Examples.adoc[]
+* xref:Testing_Kotlin_Projects.adoc[]
+* xref:Linting_Kotlin_Projects.adoc[]
+* xref:Publishing_Kotlin_Projects.adoc[]
 
 .Build Tool Comparisons
 * xref:Case_Study_Mill_vs_Maven.adoc[]

docs/modules/ROOT/pages/Bundled_Libraries.adoc

@@ -9,29 +9,29 @@ Mill comes bundled with a set of external Open Source libraries and projects.
 Project page:: https://github.com/com-lihaoyi/os-lib
 ScalaDoc:: https://javadoc.io/doc/com.lihaoyi/os-lib_2.13/latest/index.html
 
-include::example/external/libraries/1-oslib.adoc[]
+include::example/depth/libraries/1-oslib.adoc[]
 
 == uPickle
 
 Project page:: https://github.com/com-lihaoyi/upickle
 ScalaDoc:: https://javadoc.io/doc/com.lihaoyi/upickle_2.13/latest/index.html
 
-include::example/external/libraries/2-upickle.adoc[]
+include::example/depth/libraries/2-upickle.adoc[]
 
 == Requests-Scala
 
 Project page:: https://github.com/com-lihaoyi/requests-scala
 ScalaDoc:: https://javadoc.io/doc/com.lihaoyi/requests_2.13/latest/index.html
 
-include::example/external/libraries/3-requests.adoc[]
+include::example/depth/libraries/3-requests.adoc[]
 
 == MainArgs
 
 
 Project page:: https://github.com/com-lihaoyi/mainargs
 Scaladoc:: https://javadoc.io/doc/com.lihaoyi/mainargs_2.13/latest/index.html
 
-include::example/external/libraries/4-mainargs.adoc[]
+include::example/depth/libraries/4-mainargs.adoc[]
 
 == Coursier
 

docs/modules/ROOT/pages/Java_Build_Examples.adoc

@@ -21,30 +21,19 @@ Many of the APIs covered here are listed in the API documentation:
 * {mill-doc-url}/api/latest/mill/scalalib/MavenModule.html[`mill.scalalib.MavenModule`]
 * {mill-doc-url}/api/latest/mill/scalalib/JavaModule.html[`mill.scalalib.JavaModule`]
 
-== Common Configuration Overrides
-
-include::example/javalib/builds/1-common-config.adoc[]
-
-== Custom Tasks
-
-include::example/javalib/builds/2-custom-tasks.adoc[]
-
-== Overriding Tasks
-
-include::example/javalib/builds/3-override-tasks.adoc[]
 
 == Nesting Modules
 
-include::example/javalib/builds/4-nested-modules.adoc[]
+include::example/javalib/builds/1-nested-modules.adoc[]
 
 == Maven-Compatible Modules
 
-include::example/javalib/builds/8-compat-modules.adoc[]
+include::example/javalib/builds/2-compat-modules.adoc[]
 
 
 == Realistic Java Example Project
 
-include::example/javalib/builds/9-realistic.adoc[]
+include::example/javalib/builds/4-realistic.adoc[]
 
 
 == Example Builds for Real Projects

docs/modules/ROOT/pages/Java_Module_Config.adoc

@@ -11,52 +11,64 @@ for `JavaModule`.
 
 Many of the APIs covered here are listed in the API documentation:
 
-* {mill-doc-url}/api/latest/mill/scalalib/JavaModule.html[mill.javaalib.JavaModule]
+* {mill-doc-url}/api/latest/mill/scalalib/JavaModule.html[mill.javalib.JavaModule]
+
+== Common Configuration Overrides
+
+include::example/javalib/module/1-common-config.adoc[]
+
+== Custom Tasks
+
+include::example/javalib/module/2-custom-tasks.adoc[]
+
+== Overriding Tasks
+
+include::example/javalib/module/3-override-tasks.adoc[]
 
 
 == Compilation & Execution Flags
 
-include::example/javalib/module/1-compilation-execution-flags.adoc[]
+include::example/javalib/module/4-compilation-execution-flags.adoc[]
 
 == Adding Ivy Dependencies
 
-include::example/javalib/module/2-ivy-deps.adoc[]
+include::example/javalib/module/5-ivy-deps.adoc[]
 
 == Runtime and Compile-time Dependencies
 
-include::example/javalib/module/3-run-compile-deps.adoc[]
+include::example/javalib/module/6-run-compile-deps.adoc[]
 
 == Classpath and Filesystem Resources
 
-include::example/javalib/module/5-resources.adoc[]
+include::example/javalib/module/7-resources.adoc[]
 
 == Annotation Processors
 
-include::example/javalib/module/6-annotation-processors.adoc[]
+include::example/javalib/module/8-annotation-processors.adoc[]
 
 == Javadoc Config
 
-include::example/javalib/module/7-docjar.adoc[]
+include::example/javalib/module/9-docjar.adoc[]
 
 == Unmanaged Jars
 
-include::example/javalib/module/8-unmanaged-jars.adoc[]
+include::example/javalib/module/10-unmanaged-jars.adoc[]
 
 == Specifying the Main Class
 
-include::example/javalib/module/9-main-class.adoc[]
+include::example/javalib/module/11-main-class.adoc[]
 
 == Downloading Non-Maven Jars
 
-include::example/javalib/module/10-downloading-non-maven-jars.adoc[]
+include::example/javalib/module/12-downloading-non-maven-jars.adoc[]
 
 == Customizing the Assembly
 
-include::example/javalib/module/11-assembly-config.adoc[]
+include::example/javalib/module/13-assembly-config.adoc[]
 
 == Repository Config
 
-include::example/javalib/module/12-repository-config.adoc[]
+include::example/javalib/module/14-repository-config.adoc[]
 
 === Maven Central: Blocked!
 
@@ -86,5 +98,5 @@ If you are using millw, a more permanent solution could be to set the environmen
 
 == Native C Code with JNI
 
-include::example/javalib/module/13-jni.adoc[]
+include::example/javalib/module/15-jni.adoc[]
 

docs/modules/ROOT/pages/Kotlin_Build_Examples.adoc

@@ -0,0 +1,36 @@
+= Kotlin Build Examples
+
+++++
+<script>
+gtag('config', 'AW-16649289906');
+</script>
+++++
+
+On this page, we will explore the Mill build tool via a series of simple Kotlin
+example projects. Each project demonstrates one particular feature of the Mill
+build tool, and is also an executable codebase you can download and run. By the
+end of this page, you will be familiar with how to configure Mill to work with
+realistic Kotlin codebases: cross-building, testing, and publishing them.
+
+
+Many of the APIs covered here are listed in the API documentation:
+
+* {mill-doc-url}/api/latest/mill/main/RootModule.html[`mill.kotlinlib.RootModule`]
+* {mill-doc-url}/api/latest/mill/scalalib/TestModule$.html[`mill.kotlinlib.TestModule`]
+* {mill-doc-url}/api/latest/mill/scalalib/PublishModule.html[`mill.kotlinlib.PublishModule`]
+* {mill-doc-url}/api/latest/mill/kotlinlib/KotlinMavenModule.html[`mill.kotlinlib.KotlinMavenModule`]
+* {mill-doc-url}/api/latest/mill/kotlinlib/KotlinModule.html[`mill.kotlinlib.KotlinModule`]
+
+== Nesting Modules
+
+include::example/kotlinlib/builds/1-nested-modules.adoc[]
+
+== Maven-Compatible Modules
+
+include::example/kotlinlib/builds/2-compat-modules.adoc[]
+
+
+== Realistic Kotlin Example Project
+
+include::example/kotlinlib/builds/4-realistic.adoc[]
+

docs/modules/ROOT/pages/Kotlin_Module_Config.adoc

@@ -0,0 +1,104 @@
+= Kotlin Module Configuration
+
+++++
+<script>
+gtag('config', 'AW-16649289906');
+</script>
+++++
+
+This page goes into more detail about the various configuration options
+for `KotlinModule`.
+
+Many of the APIs covered here are listed in the API documentation:
+
+* {mill-doc-url}/api/latest/mill/kotlinlib/KotlinModule.html[mill.kotlinlib.KotlinModule]
+
+
+
+== Common Configuration Overrides
+
+include::example/kotlinlib/module/1-common-config.adoc[]
+
+== Custom Tasks
+
+include::example/kotlinlib/module/2-custom-tasks.adoc[]
+
+== Overriding Tasks
+
+include::example/kotlinlib/module/3-override-tasks.adoc[]
+
+
+== Compilation & Execution Flags
+
+include::example/kotlinlib/module/4-compilation-execution-flags.adoc[]
+
+== Adding Ivy Dependencies
+
+include::example/kotlinlib/module/5-ivy-deps.adoc[]
+
+== Runtime and Compile-time Dependencies
+
+include::example/kotlinlib/module/6-run-compile-deps.adoc[]
+
+== Classpath and Filesystem Resources
+
+include::example/kotlinlib/module/7-resources.adoc[]
+
+== Kotlin Compiler Plugins
+
+include::example/kotlinlib/module/8-kotlin-compiler-plugins.adoc[]
+
+== Javadoc Config
+
+include::example/kotlinlib/module/9-docjar.adoc[]
+
+== Unmanaged Jars
+
+include::example/kotlinlib/module/10-unmanaged-jars.adoc[]
+
+== Specifying the Main Class
+
+include::example/kotlinlib/module/11-main-class.adoc[]
+
+== Downloading Non-Maven Jars
+
+include::example/kotlinlib/module/12-downloading-non-maven-jars.adoc[]
+
+== Customizing the Assembly
+
+include::example/kotlinlib/module/13-assembly-config.adoc[]
+
+== Repository Config
+
+include::example/kotlinlib/module/14-repository-config.adoc[]
+
+=== Maven Central: Blocked!
+
+Under some circumstances (e.g. corporate firewalls), you may not have access maven central. The typical symptom will be error messages which look like this;
+
+----
+1 targets failed
+mill.scalalib.ZincWorkerModule.classpath
+Resolution failed for 1 modules:
+--------------------------------------------
+  com.lihaoyi:mill-scalalib-worker_2.13:0.11.1
+        not found: C:\Users\partens\.ivy2\local\com.lihaoyi\mill-scalalib-worker_2.13\0.11.1\ivys\ivy.xml
+        download error: Caught java.io.IOException (Server returned HTTP response code: 503 for URL: https://repo1.maven.org/maven2/com/lihaoyi/mill-scalalib-worker_2.13/0.11.1/mill-scalalib-worker_2.13-0.11.1.pom) while downloading https://repo1.maven.org/maven2/com/lihaoyi/mill-scalalib-worker_2.13/0.11.1/mill-scalalib-worker_2.13-0.11.1.pom
+----
+
+It is expected that basic commands (e.g. clean) will not work, as Mill saying it is unable to resolve it's own, fundamental, dependencies. Under such circumstances, you will normally have access to some proxy, or other corporate repository which resolves maven artefacts. The strategy is simply to tell mill to use that instead.
+
+The idea is to set an environment variable COURSIER_REPOSITORIES (see coursier docs). The below command should set the environment variable for the current shell, and then run the mill command.
+
+----
+ COURSIER_REPOSITORIES=https://packages.corp.com/artifactory/maven/ mill resolve _
+----
+
+If you are using millw, a more permanent solution could be to set the environment variable at the top of the millw script, or as a user environment variable etc.
+
+
+
+== Native C Code with JNI
+
+include::example/kotlinlib/module/15-jni.adoc[]
+

docs/modules/ROOT/pages/Linting_Java_Projects.adoc

@@ -9,6 +9,7 @@ gtag('config', 'AW-16649289906');
 This page will discuss common topics around enforcing the code quality of Java
 codebases using the Mill build tool
 
+
 == ErrorProne
 
 include::example/javalib/linting/1-error-prone.adoc[]
@@ -17,6 +18,10 @@ include::example/javalib/linting/1-error-prone.adoc[]
 
 include::example/javalib/linting/2-checkstyle.adoc[]
 
+== AutoFormatting with Palantir Java Format
+
+include::example/javalib/linting/3-palantirformat.adoc[]
+
 == Jacoco Code Coverage
 
 Mill supports Java code coverage analysis via the mill-jacoco plugin. See the

docs/modules/ROOT/pages/Linting_Kotlin_Projects.adoc

@@ -0,0 +1,18 @@
+= Linting Kotlin Projects
+
+++++
+<script>
+gtag('config', 'AW-16649289906');
+</script>
+++++
+
+This page will discuss common topics around enforcing the code quality of Kotlin
+codebases using the Mill build tool
+
+== Detekt
+
+include::example/kotlinlib/linting/1-detekt.adoc[]
+
+== KtLint
+
+include::example/kotlinlib/linting/2-ktlint.adoc[]

docs/modules/ROOT/pages/Linting_Scala_Projects.adoc

@@ -15,6 +15,8 @@ include::example/scalalib/linting/1-scalafmt.adoc[]
 
 == Scoverage Code Coverage
 
+include::example/scalalib/linting/2-contrib-scoverage.adoc[]
+
 Mill supports Scala code coverage analysis via the Scoverage contrib plugin. See the
 contrib plugin documentation for more details:
 

docs/modules/ROOT/pages/Publishing_Kotlin_Projects.adoc

@@ -0,0 +1,15 @@
+= Publishing Kotlin Projects
+
+++++
+<script>
+gtag('config', 'AW-16649289906');
+</script>
+++++
+
+This page will discuss common topics around publishing your Kotlin projects for others to use
+
+== Publishing Locally
+
+include::example/kotlinlib/publishing/2-publish-module.adoc[]
+
+include::partial$Publishing_Footer.adoc[]