Another pass at the docs (#3665)

* Break out `{language} Library Dependencies` from `{language} Module
Configuration`
* Move `Search for dependency updates` to `Library Dependencies in Mill`
* Remove the now-unnecessary `show` from `visualize` commands
* `import $ivy` now starts with a Java example
* `Running Mill with custom JVM options` moved to `Installation and IDE
support`

docs/modules/ROOT/nav.adoc

@@ -7,30 +7,33 @@
 * xref:javalib/installation-ide.adoc[]
 * xref:javalib/builtin-commands.adoc[]
 * xref:javalib/module-config.adoc[]
-* xref:javalib/build-examples.adoc[]
+* xref:javalib/dependencies.adoc[]
 * xref:javalib/testing.adoc[]
 * xref:javalib/linting.adoc[]
 * xref:javalib/publishing.adoc[]
+* xref:javalib/build-examples.adoc[]
 * xref:javalib/web-examples.adoc[]
 
 .xref:scalalib/intro.adoc[]
 * xref:scalalib/installation-ide.adoc[]
 * xref:scalalib/builtin-commands.adoc[]
 * xref:scalalib/module-config.adoc[]
-* xref:scalalib/build-examples.adoc[]
+* xref:scalalib/dependencies.adoc[]
 * xref:scalalib/testing.adoc[]
 * xref:scalalib/linting.adoc[]
 * xref:scalalib/publishing.adoc[]
+* xref:scalalib/build-examples.adoc[]
 * xref:scalalib/web-examples.adoc[]
 
 .xref:kotlinlib/intro.adoc[]
 * xref:kotlinlib/installation-ide.adoc[]
 * xref:kotlinlib/builtin-commands.adoc[]
 * xref:kotlinlib/module-config.adoc[]
-* xref:kotlinlib/build-examples.adoc[]
+* xref:kotlinlib/dependencies.adoc[]
 * xref:kotlinlib/testing.adoc[]
 * xref:kotlinlib/linting.adoc[]
 * xref:kotlinlib/publishing.adoc[]
+* xref:kotlinlib/build-examples.adoc[]
 
 .Build Tool Comparisons
 * xref:comparisons/maven.adoc[]

docs/modules/ROOT/pages/depth/library-deps.adoc

@@ -39,6 +39,65 @@ def ivyDeps = Agg(
 )
 ----
 
+
+== Test dependencies (there is no `test` scope)
+
+One difference between Mill and other build tools like sbt or Maven is the fact, that tests are ordinary submodules on their own.
+For convenience, most modules already come with a pre-configured trait for a test submodule,
+which already inherits all dependencies of their parent module.
+If you need additional test dependencies, you simply add them by overriding `def ivyDeps`, as you would do with normal library dependencies.
+
+When migrating a sbt project and seeing a dependency like this: `"ch.qos.logback" % "logback-classic" % "1.2.3" % "test"`,
+simply add it to the test module's `ivyDeps` as ordinary dependency.
+There is no special test scope in Mill.
+
+.Example
+[source,scala]
+----
+object main extends JavaModule {
+  object test extends JavaModuleTests {
+    def ivyDeps = Agg(
+      ivy"org.qos.logback:logback-classic:1.2.3"
+    )
+  }
+}
+----
+
+== Compile-only dependencies (`provided` scope)
+
+If you want to use a dependency only at compile time, you can declare it with the `compileIvyDeps` task.
+
+.Example
+[source,scala]
+----
+def compileIvyDeps = Agg(
+  ivy"org.slf4j:slf4j-api:1.7.25"
+)
+----
+
+When Mill generated file to interact with package manager like `pom.xml` for Maven repositories, such compile-only dependencies are mapped to the `provided` scope.
+
+Please note, that dependencies with `provided` scope will never be resolved transitively. Hence, the name "provided", as the task runtime needs to "provide" them, if they are needed.
+
+
+== Runtime dependencies
+
+If you want to declare dependencies to be used at runtime (but not at compile time), you can use the `runIvyDeps` tasks.
+
+.Example
+[source,scala]
+----
+def runIvyDeps = Agg(
+  ivy"ch.qos.logback:logback-classic:1.2.0"
+)
+----
+
+It is also possible to use a higher version of the same library dependencies already defined in `ivyDeps`, to ensure you compile against a minimal API version, but actually run with the latest available version.
+
+== Searching For Dependency Updates
+
+include::partial$example/depth/dependencies/1-search-updates.adoc[]
+
 == Scala dependencies
 
 Scala major releases up until version `2.13` are binary incompatible.
@@ -105,60 +164,6 @@ In the early development of Scala 3, the Scala 3 compiler was called "Dotty". La
 The dotty compiler itself is an implementation of the http://lampwww.epfl.ch/~amin/dot/fool.pdf[Dependent Object Types (DOT) calculus], which is the new basis of Scala 3. It also enhances the type system to a next level and allows features like union-types and intersection-types.
 --
 
-== Test dependencies (there is no `test` scope)
-
-One difference between Mill and other build tools like sbt or Maven is the fact, that tests are ordinary submodules on their own.
-For convenience, most modules already come with a pre-configured trait for a test submodule,
-which already inherits all dependencies of their parent module.
-If you need additional test dependencies, you simply add them by overriding `def ivyDeps`, as you would do with normal library dependencies.
-
-When migrating a sbt project and seeing a dependency like this: `"ch.qos.logback" % "logback-classic" % "1.2.3" % "test"`,
-simply add it to the test module's `ivyDeps` as ordinary dependency.
-There is no special test scope in Mill.
-
-.Example
-[source,scala]
-----
-object main extends JavaModule {
-  object test extends JavaModuleTests {
-    def ivyDeps = Agg(
-      ivy"org.qos.logback:logback-classic:1.2.3"
-    )
-  }
-}
-----
-
-== Compile-only dependencies (`provided` scope)
-
-If you want to use a dependency only at compile time, you can declare it with the `compileIvyDeps` task.
-
-.Example
-[source,scala]
-----
-def compileIvyDeps = Agg(
-  ivy"org.slf4j:slf4j-api:1.7.25"
-)
-----
-
-When Mill generated file to interact with package manager like `pom.xml` for Maven repositories, such compile-only dependencies are mapped to the `provided` scope.
-
-Please note, that dependencies with `provided` scope will never be resolved transitively. Hence, the name "provided", as the task runtime needs to "provide" them, if they are needed.
-
-
-== Runtime dependencies
-
-If you want to declare dependencies to be used at runtime (but not at compile time), you can use the `runIvyDeps` tasks.
-
-.Example
-[source,scala]
-----
-def runIvyDeps = Agg(
-  ivy"ch.qos.logback:logback-classic:1.2.0"
-)
-----
-
-It is also possible to use a higher version of the same library dependencies already defined in `ivyDeps`, to ensure you compile against a minimal API version, but actually run with the latest available version.
-
 == Detecting transitive dependencies
 
 To render a tree of dependencies (transitive included) you can run `mill myModule.ivyDepsTree`. Here is how the start of `./mill __.ivyDepsTree` looks like in the `mill` project itself:
@@ -288,3 +293,4 @@ To the already required Scala version, there comes the Scala Native version.
 
 You can use two colons (`::`) between `name` and `version` to define a Scala Native dependency.
 Your module needs to `extends ScalaNativeModule` to accept Scala Native dependencies.
+

docs/modules/ROOT/pages/extending/contrib-plugins.adoc

@@ -52,4 +52,4 @@ import $ivy.`com.lihaoyi::mill-contrib-bloop:`
 
 == Importing Contrib Modules
 
-include::partial$example/extending/imports/6-contrib-import.adoc[]
+include::partial$example/extending/imports/3-contrib-import.adoc[]

docs/modules/ROOT/pages/extending/import-ivy.adoc

@@ -1,5 +1,19 @@
-= import $file and import $ivy
+= import $ivy
 :page-aliases: Import_File_And_Import_Ivy.adoc
 
-include::partial$example/extending/imports/3-import-ivy.adoc[]
+// This page illustrates usage of  `import $ivy`.
+// `import $ivy` lets you import JVM dependencies into your `build.mill`, so
+// you can use arbitrary third-party libraries at build-time. This makes
+// lets you perform computations at build-time rather than run-time,
+// speeding up your application start up. `import $ivy` can be used on any
+// JVM library on Maven Central.
+//
 
+== Importing Java Libraries
+
+include::partial$example/extending/imports/1-import-ivy.adoc[]
+
+
+== Importing Scala Libraries
+
+include::partial$example/extending/imports/2-import-ivy-scala.adoc[]

docs/modules/ROOT/pages/javalib/builtin-commands.adoc

@@ -1,3 +1,8 @@
 = Built-in Commands
 :page-aliases: Java_Builtin_Commands.adoc
+
+:language: Java
+:language-small: java
+
+
 include::partial$example/javalib/basic/4-builtin-commands.adoc[]

docs/modules/ROOT/pages/javalib/dependencies.adoc

@@ -0,0 +1,32 @@
+= Java Library Dependencies
+
+++++
+<script>
+gtag('config', 'AW-16649289906');
+</script>
+++++
+
+This page goes into more detail about configuring third party dependencies
+for `JavaModule`.
+
+== Adding Ivy Dependencies
+
+include::partial$example/javalib/dependencies/1-ivy-deps.adoc[]
+
+== Runtime and Compile-time Dependencies
+
+include::partial$example/javalib/dependencies/2-run-compile-deps.adoc[]
+
+
+== Unmanaged Jars
+
+include::partial$example/javalib/dependencies/3-unmanaged-jars.adoc[]
+
+== Downloading Non-Maven Jars
+
+include::partial$example/javalib/dependencies/4-downloading-non-maven-jars.adoc[]
+
+== Repository Config
+
+include::partial$example/javalib/dependencies/5-repository-config.adoc[]
+

docs/modules/ROOT/pages/javalib/installation-ide.adoc

@@ -1,4 +1,7 @@
 = Installation and IDE Support
 :page-aliases: Java_Installation_IDE_Support.adoc
 
+:language: Java
+:language-small: java
+
 include::partial$Installation_IDE_Support.adoc[]

docs/modules/ROOT/pages/javalib/module-config.adoc

@@ -31,13 +31,6 @@ include::partial$example/javalib/module/3-override-tasks.adoc[]
 
 include::partial$example/javalib/module/4-compilation-execution-flags.adoc[]
 
-== Adding Ivy Dependencies
-
-include::partial$example/javalib/module/5-ivy-deps.adoc[]
-
-== Runtime and Compile-time Dependencies
-
-include::partial$example/javalib/module/6-run-compile-deps.adoc[]
 
 == Classpath and Filesystem Resources
 
@@ -51,50 +44,16 @@ include::partial$example/javalib/module/8-annotation-processors.adoc[]
 
 include::partial$example/javalib/module/9-docjar.adoc[]
 
-== Unmanaged Jars
-
-include::partial$example/javalib/module/10-unmanaged-jars.adoc[]
 
 == Specifying the Main Class
 
 include::partial$example/javalib/module/11-main-class.adoc[]
 
-== Downloading Non-Maven Jars
-
-include::partial$example/javalib/module/12-downloading-non-maven-jars.adoc[]
 
 == Customizing the Assembly
 
 include::partial$example/javalib/module/13-assembly-config.adoc[]
 
-== Repository Config
-
-include::partial$example/javalib/module/14-repository-config.adoc[]
-
-=== Working without access to Maven Central
-
-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 tasks 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

docs/modules/ROOT/pages/kotlinlib/dependencies.adoc

@@ -0,0 +1,36 @@
+= Kotlin Library Dependencies
+
+++++
+<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]
+
+
+
+== Adding Ivy Dependencies
+
+include::partial$example/kotlinlib/dependencies/1-ivy-deps.adoc[]
+
+== Runtime and Compile-time Dependencies
+
+include::partial$example/kotlinlib/dependencies/2-run-compile-deps.adoc[]
+
+== Unmanaged Jars
+
+include::partial$example/kotlinlib/dependencies/3-unmanaged-jars.adoc[]
+
+== Downloading Non-Maven Jars
+
+include::partial$example/kotlinlib/dependencies/4-downloading-non-maven-jars.adoc[]
+
+== Repository Config
+
+include::partial$example/kotlinlib/dependencies/5-repository-config.adoc[]