Tweak docs (com-lihaoyi#4434)

docs/modules/ROOT/pages/index.adoc

@@ -2,15 +2,18 @@
 
 include::partial$gtag-config.adoc[]
 
+https://index.scala-lang.org/com-lihaoyi/mill/mill-main[image:https://index.scala-lang.org/com-lihaoyi/mill/mill-main/latest.svg[Mill]]
+https://central.sonatype.com/artifact/com.lihaoyi/mill-dist[image:https://img.shields.io/maven-central/v/com.lihaoyi/mill-dist?label=latest-unstable-version[Maven Central Version]]
+https://www.patreon.com/lihaoyi[image:https://img.shields.io/badge/patreon-sponsor-ff69b4.svg[Patreon]]
 
 Mill is a fast, scalable, multi-language build tool that supports Java, Scala,
 Kotlin, and Python:
 
 * Mill can build the same Java codebase xref:comparisons/maven.adoc[4-10x faster than Maven],
 or xref:comparisons/gradle.adoc[2-4x faster than Gradle]
 
-* Mill's rich builtin featureset lets you
-build and xref:javalib/publishing.adoc[publish] your project easily without third-party plugins.
+* Mill bundles all the tools needed to develop and publish your project builtin
+without needing plugins
 
 * Mill's typed config language and immutable xref:depth/design-principles.adoc[task graph]
 helps keep builds clean and understandable
@@ -50,14 +53,15 @@ CI validation times short by only running the tests necessary to validate a code
 
 * *Builtins*: Mill has builtin support for most common workflows: not just compile/run/test, but also xref:javalib/linting.adoc#_autoformatting_with_palantir_java_format[autoformatting],
 xref:javalib/linting.adoc#_linting_with_checkstyle[linting],
-xref:javalib/publishing.adoc#_publishing_to_sonatype_maven_central[publishing to Maven Central],
-xref:javalib/publishing.adoc#_building_native_image_binaries_with_graal_vm[building native binaries]
+xref:javalib/publishing.adoc#_publishing_to_sonatype_maven_central[publishing],
+building xref:javalib/publishing.adoc#_building_executable_assemblies[executable assemblies],
+xref:javalib/publishing.adoc#_building_native_image_binaries_with_graal_vm[native binaries]
 or xref:javalib/publishing.adoc#_java_installers_using_jpackage[installers],
 etc. This lets you focus on your actual project and spend less time
 fiddling with tooling and plugins.
 
 * *Maintainability*: Mill's config and xref:javalib/intro.adoc#_custom_build_logic[custom logic]
-is written in xref:depth/why-scala.adoc[concise type-checked Scala code],
+is written in xref:depth/why-scala.adoc[concise type-checked JVM code],
 with an immutable xref:depth/design-principles.adoc[module tree and task graph]. This
 catches config issues early, and helps both humans and IDEs
 (xref:cli/installation-ide.adoc#_intellij[IntelliJ] or

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

@@ -5,7 +5,7 @@ include::partial$gtag-config.adoc[]
 
 This page will discuss common topics around packaging and publishing your Java projects for others to use
 
-== Customizing the Executable Assembly
+== Building Executable Assemblies
 
 include::partial$example/javalib/publishing/1-assembly-config.adoc[]
 

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

@@ -6,7 +6,7 @@ include::partial$gtag-config.adoc[]
 This page will discuss common topics around packaging and publishing your Kotlin projects for others to use
 
 
-== Customizing the Executable Assembly
+== Building Executable Assemblies
 
 include::partial$example/kotlinlib/publishing/1-assembly-config.adoc[]
 

docs/modules/ROOT/pages/scalalib/publishing.adoc

@@ -5,7 +5,7 @@ include::partial$gtag-config.adoc[]
 
 This page will discuss common topics around packaging and publishing your Scala projects for others to use
 
-== Customizing the Executable Assembly
+== Building Executable Assemblies
 
 include::partial$example/scalalib/publishing/1-assembly-config.adoc[]
 

example/scalalib/publishing/1-assembly-config/build.mill

@@ -1,3 +1,6 @@
+// Mill's built in `.assembly` task makes it easy to generate an executable assembly
+// jar from any JVM module. You can also customize the assembly jar as shown below:
+
 //// SNIPPET:BUILD
 package build
 import mill._, scalalib._
@@ -17,17 +20,21 @@ object foo extends ScalaModule {
     // the `shapeless` package will be relocated under the `shade` package
     Rule.Relocate("shapeless.**", "shade.shapless.@1")
   )
+
+  // def manifest: T[JarManifest]
+  // def prependShellScript: T[String]
 }
 
 object bar extends ScalaModule {
   def scalaVersion = "2.13.8"
 }
 //// SNIPPET:END
 
-// When you make a runnable jar of your project with the `.assembly` task,
-// you may want to exclude some files from a final jar (like signature files,
-// and manifest files from library jars), and merge duplicated files (for
-// instance `reference.conf` files from library dependencies).
+// The most common way of configuring an assembly is
+// excluding some files from a final jar (like signature files,
+// and manifest files from library jars), and merging duplicated files (for
+// instance `reference.conf` files from library dependencies). This is
+// done by overriding `def assemblyRules` as shown above
 //
 // By default mill excludes all `+*.sf+`, `+*.dsa+`, `+*.rsa+`, and
 // `META-INF/MANIFEST.MF` files from assembly, and concatenates all

readme.adoc

@@ -18,13 +18,25 @@ ifdef::env-github[]
 :warning-caption: :warning:
 endif::[]
 
-{link-github}/actions/workflows/run-tests.yml[image:{link-github}/actions/workflows/run-tests.yml/badge.svg[Build and Release]]
 https://index.scala-lang.org/com-lihaoyi/mill/mill-main[image:https://index.scala-lang.org/com-lihaoyi/mill/mill-main/latest.svg[Mill]]
 https://central.sonatype.com/artifact/com.lihaoyi/mill-dist[image:https://img.shields.io/maven-central/v/com.lihaoyi/mill-dist?label=latest-unstable-version[Maven Central Version]]
 https://www.patreon.com/lihaoyi[image:https://img.shields.io/badge/patreon-sponsor-ff69b4.svg[Patreon]]
 
-Mill is a fast JVM build tool that supports Java and Scala. Mill aims to make your 
-project’s build process performant, maintainable, and flexible.
+
+Mill is a fast, scalable, multi-language build tool that supports Java, Scala,
+Kotlin, and Python:
+
+* Mill can build the same Java codebase 4-10x faster than Maven,
+or 2-4x faster than Gradle
+
+* Mill bundles all the tools needed to develop and publish your project builtin
+without needing plugins
+
+* Mill's typed config language and immutable task graph
+helps keep builds clean and understandable
+
+* Mill scales well from small projects to
+large multi-language monorepos with hundreds of modules
 
 If you want to use Mill in your own projects, check out our documentation: