Integrate kotlin example into docs (#3544)

* Added `Kotlin_Intro_to_Mill.adoc`,
`Kotlin_Installation_IDE_Support.adoc`, `Kotlin_Builtin_Commands.adoc`
pages
* Fixed an issue with inherited example adoc pages not rendering
correctly since #3398

docs/modules/ROOT/nav.adoc

@@ -27,6 +27,10 @@
 * xref:Scala_Web_Examples.adoc[]
 * xref:Case_Study_Mill_vs_SBT.adoc[]
 
+.xref:Kotlin_Intro_to_Mill.adoc[]
+* xref:Kotlin_Installation_IDE_Support.adoc[]
+* xref:Kotlin_Builtin_Commands.adoc[]
+
 // This section is all about developing a deeper understanding of specific
 // topics in Mill. This is the opposite of `Quick Start` above: while we touch
 // on some end-user use cases, it is only to motivate the Mill features that we

docs/modules/ROOT/pages/Java_Builtin_Commands.adoc

@@ -1,12 +1,3 @@
 = Built-in Commands
 
-Mill comes with a number of useful commands out of the box. These are listed
-in the Scaladoc:
-
-* {mill-doc-url}/api/latest/mill/main/MainModule.html[mill.main.MainModule]
-
-Mill's built-in commands are typically not directly related to building your
-application code, but instead are utilities that help you understand and work
-with your Mill build.
-
 include::example/javalib/basic/4-builtin-commands.adoc[]

docs/modules/ROOT/pages/Java_Intro_to_Mill.adoc

@@ -32,61 +32,7 @@ can be used for applications built on top of common Java frameworks like
 xref:Java_Web_Examples.adoc#_spring_boot_todomvc_app[Spring Boot] or
 xref:Java_Web_Examples.adoc#_micronaut_todomvc_app[Micronaut].
 
-Mill borrows ideas from other tools like https://maven.apache.org/[Maven],
-https://gradle.org/[Gradle], https://bazel.build/[Bazel], but tries to learn from the
-strengths of each tool and improve on their weaknesses. Although Maven and Gradle
-are mature widely-used tools, they have fundamental limitations in their design
-(https://blog.ltgt.net/maven-is-broken-by-design/[Maven Design],
-https://www.bruceeckel.com/2021/01/02/the-problem-with-gradle/[Gradle Design]) that make
-them difficult to improve upon incrementally.
-
-xref:Case_Study_Mill_vs_Maven.adoc[Compared to Maven]:
-
-* **Mill follows Maven's innovation of good built-in defaults**: Mill's built-in
-  ``JavaModule``s follow Maven's "convention over configuration" style. Small mill
-  projects require minimal effort to get started, and larger Mill projects have a consistent
-  structure building on these defaults.
-
-* **Mill makes customizing the build tool much easier than Maven**. Projects usually
-  grow beyond just compiling a single language: needing custom
-  code generation, linting workflows, output artifacts, or support for
-  additional languages. Mill makes doing this yourself easy, so you are not beholden
-  to third-party plugins that may not exist, be well maintained, or interact well with each other.
-
-* **Mill automatically caches and parallelizes your build**: Not just the
-  built-in tasks that Mill ships with, but also any custom tasks or modules.
-  This maximizes performance and snappiness of
-  your command-line build workflows, and especially matters in larger codebases where builds
-  tend to get slow: a Maven `clean install` taking over a minute might take just a 
-  few seconds in Mill.
-
-xref:Case_Study_Mill_vs_Gradle.adoc[Compared to Gradle]:
-
-* **Mill follows Gradle's conciseness**: Rather than pages and pages of verbose XML, every
-  line in a Mill build is meaningful. e.g. adding a dependency is 1 line in
-  Mill, like it is in Gradle, and unlike the 5 line `<dependency>` declaration you find in Maven.
-  Skimming and understanding a 100-line Mill `build.mill` file is
-  often much easier than skimming the equivalent 500-line Maven `pom.xml`.
-
-* **Mill builds more performant**: Although both Mill and Gradle automatically cache and
-  parallelize your build, Mill does so with much less fixed overhead, resulting in 2-3x
-  speedups in common command-line workflows. This means less time waiting for your build
-  tool, and more time focusing on the things that really matter to your project.
-
-* **Mill enforces best practices by default**. All Mill tasks are cached by default, even
-  custom tasks. All Mill tasks write their output to disk xref:Out_Dir.adoc[a
-  standard place]. All task inter-dependencies are automatically captured, without
-  needing manual annotation. All Mill builds are incremental, not just tasks but also
-  xref:The_Mill_Evaluation_Model.adoc#_caching_at_each_layer_of_the_evaluation_model[configuration
-  and other phases]. Where Gradle requires considerable
-  https://docs.gradle.org/current/userguide/incremental_build.html[effort and expertise]
-  to maintain your build, Mill automates it so the
-  easiest thing to do is almost always the right thing to do.
-
-Mill build files are written in Scala, but you do not need to have prior experience
-in Scala to read or write them. Like Gradle Groovy or Maven XML, it's easy to learn
-enough Scala for Mill without needing to become an expert in the language.
-
+include::partial$Intro_Maven_Gradle_Comparison.adoc[]
 
 include::partial$Intro_to_Mill_BlogVideo.adoc[]
 

docs/modules/ROOT/pages/Kotlin_Builtin_Commands.adoc

@@ -0,0 +1,3 @@
+= Built-in Commands
+
+include::example/kotlinlib/basic/4-builtin-commands.adoc[]

docs/modules/ROOT/pages/Kotlin_Installation_IDE_Support.adoc

@@ -0,0 +1,3 @@
+= Installation and IDE Support
+
+include::partial$Installation_IDE_Support.adoc[]

docs/modules/ROOT/pages/Kotlin_Intro_to_Mill.adoc

@@ -0,0 +1,48 @@
+
+// Author Notes:
+//
+// This is the first page a user is expected to land on when learning about
+// Mill. It is designed to be a quick, broad overview to get someone started:
+// what is Mill, why should they care, and what some simple Mill builds look
+// like and how to use them. We intentionally touch shallowly on a lot of
+// topics without giving them a proper discussion, since the other pages have
+// plenty of space to go in-depth.
+//
+// By the end of this page, a prospective Mill user should be familiar with
+// what Mill is, hopefully have downloaded an example to try out, and be
+// interested in learning more about the Mill build tool
+
+= Introduction to Mill for Kotlin
+
+++++
+<script>
+gtag('config', 'AW-16649289906');
+</script>
+++++
+
+:language: Kotlin
+
+include::partial$Intro_to_Mill_Header.adoc[]
+
+
+include::partial$Intro_Maven_Gradle_Comparison.adoc[]
+
+Mill's Kotlin support originated as the third-party plugin
+https://github.com/lefou/mill-kotlin[lefou/mill-kotlin], which was later included with
+the main Mill codebase.
+
+include::partial$Intro_to_Mill_BlogVideo.adoc[]
+
+== Simple Kotlin Module
+
+include::example/kotlinlib/basic/1-simple.adoc[]
+
+== Custom Build Logic
+
+include::example/kotlinlib/basic/2-custom-build-logic.adoc[]
+
+== Multi-Module Project
+
+include::example/kotlinlib/basic/3-multi-module.adoc[]
+
+include::partial$Intro_to_Mill_Footer.adoc[]

docs/modules/ROOT/pages/Scala_Builtin_Commands.adoc

@@ -2,14 +2,6 @@
 
 :page-aliases: Scala_Builtin_Commands.adoc
 
-Mill comes with a number of useful commands out of the box. These are listed
-in the Scaladoc:
-
-* {mill-doc-url}/api/latest/mill/main/MainModule.html[mill.main.MainModule]
-
-Mill's built-in commands are typically not directly related to building your
-application code, but instead are utilities that help you understand and work
-with your Mill build.
 
 include::example/scalalib/basic/4-builtin-commands.adoc[]
 

docs/modules/ROOT/partials/Intro_Maven_Gradle_Comparison.adoc

@@ -0,0 +1,57 @@
+
+
+Mill borrows ideas from other tools like https://maven.apache.org/[Maven],
+https://gradle.org/[Gradle], https://bazel.build/[Bazel], but tries to learn from the
+strengths of each tool and improve on their weaknesses. Although Maven and Gradle
+are mature widely-used tools, they have fundamental limitations in their design
+(https://blog.ltgt.net/maven-is-broken-by-design/[Maven Design],
+https://www.bruceeckel.com/2021/01/02/the-problem-with-gradle/[Gradle Design]) that make
+them difficult to improve upon incrementally.
+
+xref:Case_Study_Mill_vs_Maven.adoc[Compared to Maven]:
+
+* **Mill follows Maven's innovation of good built-in defaults**: Mill's built-in
+  ``JavaModule``s follow Maven's "convention over configuration" style. Small mill
+  projects require minimal effort to get started, and larger Mill projects have a consistent
+  structure building on these defaults.
+
+* **Mill makes customizing the build tool much easier than Maven**. Projects usually
+  grow beyond just compiling a single language: needing custom
+  code generation, linting workflows, output artifacts, or support for
+  additional languages. Mill makes doing this yourself easy, so you are not beholden
+  to third-party plugins that may not exist, be well maintained, or interact well with each other.
+
+* **Mill automatically caches and parallelizes your build**: Not just the
+  built-in tasks that Mill ships with, but also any custom tasks or modules.
+  This maximizes performance and snappiness of
+  your command-line build workflows, and especially matters in larger codebases where builds
+  tend to get slow: a Maven `clean install` taking over a minute might take just a 
+  few seconds in Mill.
+
+xref:Case_Study_Mill_vs_Gradle.adoc[Compared to Gradle]:
+
+* **Mill follows Gradle's conciseness**: Rather than pages and pages of verbose XML, every
+  line in a Mill build is meaningful. e.g. adding a dependency is 1 line in
+  Mill, like it is in Gradle, and unlike the 5 line `<dependency>` declaration you find in Maven.
+  Skimming and understanding a 100-line Mill `build.mill` file is
+  often much easier than skimming the equivalent 500-line Maven `pom.xml`.
+
+* **Mill builds more performant**: Although both Mill and Gradle automatically cache and
+  parallelize your build, Mill does so with much less fixed overhead, resulting in 2-3x
+  speedups in common command-line workflows. This means less time waiting for your build
+  tool, and more time focusing on the things that really matter to your project.
+
+* **Mill enforces best practices by default**. All Mill tasks are cached by default, even
+  custom tasks. All Mill tasks write their output to disk xref:Out_Dir.adoc[a
+  standard place]. All task inter-dependencies are automatically captured, without
+  needing manual annotation. All Mill builds are incremental, not just tasks but also
+  xref:The_Mill_Evaluation_Model.adoc#_caching_at_each_layer_of_the_evaluation_model[configuration
+  and other phases]. Where Gradle requires considerable
+  https://docs.gradle.org/current/userguide/incremental_build.html[effort and expertise]
+  to maintain your build, Mill automates it so the
+  easiest thing to do is almost always the right thing to do.
+
+Mill build files are written in Scala, but you do not need to have prior experience
+in Scala to read or write them. Like Gradle Groovy or Maven XML, it's easy to learn
+enough Scala for Mill without needing to become an expert in the language.
+

example/package.mill

@@ -89,6 +89,16 @@ object `package` extends RootModule with Module {
     val upstreamOpt = upstreamCross(this.millModuleSegments.parts.dropRight(1).last)
       .flatMap(_.valuesToModules.get(List(crossValue)))
 
+    def testRepoRoot = T{
+      os.copy(super.testRepoRoot().path, T.dest, mergeFolders = true)
+      for(suffix <- Seq("build.sc", "build.mill", "build.mill.scala")){
+        for (lines <- buildScLines() if os.exists(T.dest / suffix)) {
+          os.write.over(T.dest / suffix, lines.mkString("\n"))
+        }
+      }
+      PathRef(T.dest)
+    }
+
     def resources = upstreamOpt match {
       case None => T{ Seq(super.testRepoRoot()) }
       case Some(upstream) => T{

example/scalalib/basic/4-builtin-commands/build.mill

@@ -1,3 +1,12 @@
+// Mill comes with a number of useful commands out of the box. These are listed
+// in the API Docs:
+//
+// * {mill-doc-url}/api/latest/mill/main/MainModule.html[mill.main.MainModule]
+//
+// Mill's built-in commands are typically not directly related to building your
+// application code, but instead are utilities that help you understand and work
+// with your Mill build.
+//
 // == Example `build.mill`
 //
 // The following examples will be assuming the `build.mill` file given below: