Reformat and rearrange docs (#1402)

Author: Goooler

docs/README.md

@@ -6,10 +6,9 @@
 # Introduction
 
 Shadow is a Gradle plugin for combining a project's dependency classes and resources into a single
-output Jar.
-The combined Jar is often referred to a _fat-jar_ or _uber-jar_.
-Shadow utilizes [`JarInputStream`][JarInputStream] and [`JarOutputStream`][JarOutputStream] to efficiently process dependent libraries
-into the output jar without incurring the I/O overhead of expanding the jars to disk.
+output Jar. The combined Jar is often referred to a _fat-jar_ or _uber-jar_.
+Shadow utilizes [`JarInputStream`][JarInputStream] and [`JarOutputStream`][JarOutputStream] to efficiently process
+dependent libraries into the output jar without incurring the I/O overhead of expanding the jars to disk.
 
 !!! warning "Plugin ID Change"
 

docs/about/README.md

@@ -1,7 +1,7 @@
 # About This Project
 
-I (John Engelman) started this project in December 2012. We were working on converting from a monolithic application into the
-new hot jazz of "microservices" using Dropwizard.
+I (John Engelman) started this project in December 2012. We were working on converting from a monolithic application
+into the new hot jazz of "microservices" using Dropwizard.
 I had also just started learning about Gradle and I knew that the incremental build system it provided would benefit
 our development team greatly.
 Unfortunately, the closest thing that Gradle had to Maven's Shade plugin was its ability to create application TARs and

docs/changes/README.md

@@ -3,7 +3,6 @@
 The [`ShadowJar`][ShadowJar] task type extends from Gradle's [`Jar`][Jar] type.
 This means that all attributes and methods available on [`Jar`][Jar] are also available on [`ShadowJar`][ShadowJar].
 
-
 ## Configuring Output Name
 
 Shadow configures the default [`ShadowJar`][ShadowJar] task to set the output JAR's
@@ -17,7 +16,7 @@ Shadow configures the default [`ShadowJar`][ShadowJar] task to set the output JA
 - [`destinationDirectory`][destinationDirectory]
 
 to the same default values as Gradle does for all [`Jar`][Jar] tasks. Additionally, it configures the
-[`archiveClassifier`][archiveClassifier] to be `all`. The listed ones are not full, you can view all the properties in 
+[`archiveClassifier`][archiveClassifier] to be `all`. The listed ones are not full, you can view all the properties in
 [`Jar`][Jar]. The output shadowed JAR file will be named with the following format:
 
 ```
@@ -46,7 +45,6 @@ of the shadowed JAR file. e.g.
 
 This will result in the output file being named `myApp-all.jar` instead of `myApp-1.0-all.jar`.
 
-
 ## Configuring the Runtime Classpath
 
 Each Java JAR file contains a manifest file that provides metadata about the contents of the JAR file itself.
@@ -61,10 +59,10 @@ Think of `configurations.shadow` as unmerged, runtime dependencies.
 The integration with the [`maven-publish`][maven-publish] plugin will automatically configure dependencies added
 to `configurations.shadow` as `RUNTIME` scope dependencies in the resulting POM file.
 
-Additionally, Shadow automatically configures the manifest of the [`ShadowJar`][ShadowJar] task to contain a `Class-Path` entry
-in the JAR manifest.
-The value of the `Class-Path` entry is the name of all dependencies resolved in the `shadow` configuration
-for the project.
+Additionally, Shadow automatically configures the manifest of the [`ShadowJar`][ShadowJar] task to contain a
+`Class-Path` entry in the JAR manifest.
+The value of the `Class-Path` entry is the name of all dependencies resolved in the `shadow` configuration for the
+project.
 
 === "Kotlin"
 
@@ -93,9 +91,10 @@ When deploying a shadowed JAR as an execution JAR, it is important to note that
 
 ## Configuring the JAR Manifest
 
-Beyond the automatic configuration of the `Class-Path` entry, the [`ShadowJar`][ShadowJar] manifest is configured in a number of ways.
-First, the manifest for the [`ShadowJar`][ShadowJar] task is configured to __inherit__ from the manifest of the standard [`Jar`][Jar] task.
-This means that any configuration performed on the [`Jar`][Jar] task will propagate to the [`ShadowJar`][ShadowJar] tasks.
+Beyond the automatic configuration of the `Class-Path` entry, the [`ShadowJar`][ShadowJar] manifest is configured in a
+number of ways. First, the manifest for the [`ShadowJar`][ShadowJar] task is configured to __inherit__ from the
+manifest of the standard [`Jar`][Jar] task. This means that any configuration performed on the [`Jar`][Jar] task
+will propagate to the [`ShadowJar`][ShadowJar] tasks.
 
 === "Kotlin"
 
@@ -123,8 +122,8 @@ Inspecting the `META-INF/MANIFEST.MF` entry in the JAR file will reveal the foll
 Class-Path: /libs/a.jar
 ```
 
-If it is desired to inherit a manifest from a JAR task other than the standard [`Jar`][Jar] task, the `inheritFrom` methods
-on the `shadowJar.manifest` object can be used to configure the upstream.
+If it is desired to inherit a manifest from a JAR task other than the standard [`Jar`][Jar] task, the `inheritFrom`
+methods on the `shadowJar.manifest` object can be used to configure the upstream.
 
 === "Kotlin"
 

docs/configuration/README.md

@@ -1,8 +1,9 @@
 # Configuring Shadowed Dependencies
 
-Shadow configures the default [`ShadowJar`][ShadowJar] task to merge all dependencies from the project's `runtimeClasspath` configuration
-into the final JAR. The configurations from which to source dependencies for the merging can be configured using the
-[`configurations`][ShadowJar.configurations] property of the [`ShadowJar`][ShadowJar] task type.
+Shadow configures the default [`ShadowJar`][ShadowJar] task to merge all dependencies from the project's
+`runtimeClasspath` configuration into the final JAR. The configurations from which to source dependencies for the
+merging can be configured using the [`configurations`][ShadowJar.configurations] property of the
+[`ShadowJar`][ShadowJar] task type.
 
 === "Kotlin"
 
@@ -20,14 +21,15 @@ into the final JAR. The configurations from which to source dependencies for the
     }
     ```
 
-The above code sample would configure the [`ShadowJar`][ShadowJar] task to merge dependencies from only the `compileClasspath` configuration.
+The above code sample would configure the [`ShadowJar`][ShadowJar] task to merge dependencies from only the
+`compileClasspath` configuration.
 This means any dependency declared in the `runtimeOnly` configuration would be **not** be included in the final JAR.
 
 > Note the literal use of [`project.configurations`][Project.configurations] when setting the
-[`configurations`][ShadowJar.configurations] attribute of a [`ShadowJar`][ShadowJar] task.
-This is **required**. It may be tempting to specify `configurations = [configurations.compileClasspath]` but this will not
-have the intended effect, as `configurations.compile` will try to delegate to the
-[`configurations`][ShadowJar.configurations] property of the [`ShadowJar`][ShadowJar] task instead of the `project`
+> [`configurations`][ShadowJar.configurations] attribute of a [`ShadowJar`][ShadowJar] task.
+> This is **required**. It may be tempting to specify `configurations = [configurations.compileClasspath]` but this will
+> not have the intended effect, as `configurations.compile` will try to delegate to the
+> [`configurations`][ShadowJar.configurations] property of the [`ShadowJar`][ShadowJar] task instead of the `project`
 
 ## Embedding Jar Files Inside Your Shadow Jar
 
@@ -134,8 +136,8 @@ Gradle's [`project.configurations`][Project.configurations] block.
     ```
 
 > While not being able to filter entire transitive dependency graphs might seem like an oversight, it is necessary
-because it would not be possible to intelligently determine the build author's intended results when there is a
-common dependency between two 1st level dependencies when one is excluded and the other is not.
+> because it would not be possible to intelligently determine the build author's intended results when there is a
+> common dependency between two 1st level dependencies when one is excluded and the other is not.
 
 ### Using Regex Patterns to Filter Dependencies
 

docs/configuration/dependencies/README.md

@@ -23,9 +23,8 @@ source set or _any_ of the dependencies to be merged.
     }
     ```
 
-
-Excludes and includes can be combined just like a normal [`Jar`][Jar] task, with `excludes` taking precedence over `includes`.
-Additionally, ANT style patterns can be used to match multiple files.
+Excludes and includes can be combined just like a normal [`Jar`][Jar] task, with `excludes` taking precedence over
+`includes`. Additionally, ANT style patterns can be used to match multiple files.
 
 === "Kotlin"
 

docs/configuration/filtering/README.md

@@ -46,7 +46,8 @@ should process a particular entry and apply any modifications before writing the
     }
     ```
 
-Additionally, a [`ResourceTransformer`][ResourceTransformer] can accept a `Closure` to configure the provided `ResourceTransformer`.
+Additionally, a [`ResourceTransformer`][ResourceTransformer] can accept a `Closure` to configure the provided
+[`ResourceTransformer`][ResourceTransformer].
 
 === "Kotlin"
 
@@ -320,7 +321,6 @@ this transformer.
     }
     ```
 
-
 ## Appending XML Files
 
 XML files require a special transformer for merging. The [`XmlAppendingTransformer`][XmlAppendingTransformer]
@@ -357,11 +357,12 @@ It must be added using the [`transform`][ShadowJar.transform] methods.
 - `FAIL`: Throw a `DuplicateFileCopyingException` when subsequent items are to be created at the same path.
 - `INCLUDE`: Do not attempt to prevent duplicates.
 - `INHERIT`: Uses the same strategy as the parent copy specification.
-- `WARN`: Do not attempt to prevent duplicates, but log a warning message when multiple items are to be created at the same path.
+- `WARN`: Do not attempt to prevent duplicates, but log a warning message when multiple items are to be created at the
+  same path.
 
 see more details about them in [`DuplicatesStrategy`][DuplicatesStrategy].
 
-`ShadowJar` recognizes `DuplicatesStrategy.INCLUDE` as the default, if you want to change the strategy, you can 
+`ShadowJar` recognizes `DuplicatesStrategy.INCLUDE` as the default, if you want to change the strategy, you can
 override it like:
 
 === "Kotlin"
@@ -385,7 +386,8 @@ Different strategies will lead to different results for `foo/bar` files in the J
 - `EXCLUDE`: The **first** `foo/bar` file will be included in the final JAR.
 - `FAIL`: **Fail** the build with a `DuplicateFileCopyingException` if there are duplicated `foo/bar` files.
 - `INCLUDE`: The **last** `foo/bar` file will be included in the final JAR (the default behavior).
-- `INHERIT`: **Fail** the build with an exception like `Entry .* is a duplicate but no duplicate handling strategy has been set`.
+- `INHERIT`: **Fail** the build with an exception like
+  `Entry .* is a duplicate but no duplicate handling strategy has been set`.
 - `WARN`: The **last** `foo/bar` file will be included in the final JAR, and a warning message will be logged.
 
 **NOTE:** The `duplicatesStrategy` takes precedence over transforming and relocating. If you mix the usages of
@@ -412,7 +414,7 @@ Different strategies will lead to different results for `foo/bar` files in the J
 The [`ServiceFileTransformer`][ServiceFileTransformer] will not work as expected because the `duplicatesStrategy` will
 exclude the duplicated service files beforehand. However, this behavior might be what you expected for duplicated
 `foo/bar` files, preventing them from being included.
-Want `ResourceTransformer`s and `duplicatesStrategy` to work together? There is a way to achieve this, leave the 
+Want `ResourceTransformer`s and `duplicatesStrategy` to work together? There is a way to achieve this, leave the
 `duplicatesStrategy` as `INCLUDE` and declare a custom [`ResourceTransformer`][ResourceTransformer] to handle the
 duplicated files.
 

docs/configuration/merging/README.md

@@ -1,6 +1,7 @@
 # Minimizing
 
-Shadow can automatically remove all classes of dependencies that are not used by the project, thereby minimizing the resulting shadowed JAR.
+Shadow can automatically remove all classes of dependencies that are not used by the project, thereby minimizing the
+resulting shadowed JAR.
 
 === "Kotlin"
 
@@ -43,7 +44,8 @@ a `dependency` is interpreted as a regular expression.
     }
     ```
 
-> Dependencies scoped as `api` will be automatically excluded from minimization and used as "entry points" on minimization.
+> Dependencies scoped as `api` will be automatically excluded from minimization and used as "entry points" on
+> minimization.
 
 Similar to dependencies, projects can also be excluded.
 
@@ -68,4 +70,4 @@ Similar to dependencies, projects can also be excluded.
     ```
 
 > When excluding a `project`, all dependencies of the excluded `project` are automatically
-  excluded as well.
+> excluded as well.

docs/configuration/minimizing/README.md

@@ -32,17 +32,16 @@ In the resulting JAR, the class file is relocated from `junit/framework/TestCase
 `shadow/junit/TestCase.class`.
 
 > Relocation operates at a package level.
-It is not necessary to specify any patterns for matching, it will operate simply on the prefix
-provided.
+> It is not necessary to specify any patterns for matching, it will operate simply on the prefix provided.
 
 > Relocation will be applied globally to all instances of the matched prefix.
-That is, it does **not** scope to _only_ the dependencies being shadowed.
-Be specific as possible when configuring relocation as to avoid unintended relocations.
+> That is, it does **not** scope to _only_ the dependencies being shadowed.
+> Be specific as possible when configuring relocation as to avoid unintended relocations.
 
 ## Filtering Relocation
 
 Specific classes or files can be `included`/`excluded` from the relocation operation if necessary. Use
-[Ant Path Matcher](https://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/util/AntPathMatcher.html) 
+[Ant Path Matcher](https://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/util/AntPathMatcher.html)
 syntax to specify matching path for your files and directories.
 
 === "Kotlin"
@@ -71,8 +70,8 @@ syntax to specify matching path for your files and directories.
     }
     ```
 
-For a more advanced path matching you might want to use [Regular Expressions](https://regexr.com/) instead. Wrap the expression in `%regex[]` before
-passing it to `include`/`exclude`.
+For a more advanced path matching you might want to use [Regular Expressions](https://regexr.com/) instead. Wrap the
+expression in `%regex[]` before passing it to `include`/`exclude`.
 
 === "Kotlin"
 
@@ -96,8 +95,8 @@ passing it to `include`/`exclude`.
 
 ## Automatically Relocating Dependencies
 
-Shadow is shipped with a task that can be used to automatically configure all packages from all dependencies to be relocated.
-This feature was formally shipped into a 2nd plugin (`com.github.johnrengelman.plugin-shadow`) but has been
+Shadow is shipped with a task that can be used to automatically configure all packages from all dependencies to be
+relocated. This feature was formally shipped into a 2nd plugin (`com.github.johnrengelman.plugin-shadow`) but has been
 removed for clarity reasons in version 4.0.0.
 
 To configure automatic dependency relocation, set `enableRelocation = true` and optionally specify a custom
@@ -124,13 +123,13 @@ To configure automatic dependency relocation, set `enableRelocation = true` and
 In versions before 8.1.0 it was necessary to configure a separate `ConfigureShadowRelocation` task for this.
 
 > Configuring package auto relocation can add significant time to the shadow process as it will process all dependencies
-in the configurations declared to be shadowed. By default, this is the `runtime` or `runtimeClasspath` configurations.
-Be mindful that some Gradle plugins will automatically add dependencies to your class path. You may need to remove these 
-dependencies if you do not intend to shadow them into your library.
+> in the configurations declared to be shadowed. By default, this is the `runtime` or `runtimeClasspath` configurations.
+> Be mindful that some Gradle plugins will automatically add dependencies to your class path. You may need to remove these
+> dependencies if you do not intend to shadow them into your library.
 
 ## Relocating Project Resources Only
 
-If you want to relocate the resources of the project only and exclude all dependencies (related to a normal JAR but with 
+If you want to relocate the resources of the project only and exclude all dependencies (related to a normal JAR but with
 relocating), you can try out the trick like:
 
 === "Kotlin"
@@ -153,5 +152,5 @@ relocating), you can try out the trick like:
     }
     ```
 
-This is useful in some cases like [#759](https://github.com/GradleUp/shadow/issues/759) mentioned. See 
+This is useful in some cases like [#759](https://github.com/GradleUp/shadow/issues/759) mentioned. See
 [Configuring Shadowed Dependencies](../dependencies/README.md) for more information about `configurations`.

docs/configuration/relocation/README.md

@@ -1,6 +1,9 @@
 # Reproducible Builds
 
-By default, JAR files generated by Gradle (with or without Shadow) for a single project with the same source code may not be identical to each other. Sometimes it's desirable to configure a project to consistently output a byte-for-byte identical JAR on every build. Gradle supports this with the following configuration, and Shadow will correctly respect these settings too:
+By default, JAR files generated by Gradle (with or without Shadow) for a single project with the same source code may
+not be identical to each other. Sometimes it's desirable to configure a project to consistently output a byte-for-byte
+identical JAR on every build. Gradle supports this with the following configuration, and Shadow will correctly respect
+these settings too:
 
 === "Kotlin"
 
@@ -20,6 +23,10 @@ By default, JAR files generated by Gradle (with or without Shadow) for a single
     }
     ```
 
-One effect that this configuration will have is that the timestamps of all files in the JAR will be reset to a single consistent value. If your code or any files being included into the JAR depend on the timestamps being set accurately within the JAR, then this may not be the correct choice for you.
+One effect that this configuration will have is that the timestamps of all files in the JAR will be reset to a single
+consistent value. If your code or any files being included into the JAR depend on the timestamps being set accurately
+within the JAR, then this may not be the correct choice for you.
 
-See the [Reproducible archives section in Gradle's documentation](https://docs.gradle.org/4.9/userguide/working_with_files.html#sec:reproducible_archives) for more information.
+See
+the [Reproducible archives section in Gradle's documentation](https://docs.gradle.org/4.9/userguide/working_with_files.html#sec:reproducible_archives)
+for more information.