docs: allow and use dynamic usage output in readme

Author: simschla

README.md

@@ -83,6 +83,54 @@ To see all available options and formatters, run:
 spotless --help
 ```
 
+This will show you the available options and formatters as such:
+
+<!---freshmark usage_main
+output =
+   '```shell\n' +
+   {{usage.main.array}}.join('\n') +
+    '\n```';
+-->
+
+```shell
+                     __  __
+   _________  ____  / /_/ /__  __________
+  / ___/ __ \/ __ \/ __/ / _ \/ ___/ ___/
+ (__  ) /_/ / /_/ / /_/ /  __(__  |__  )
+/____/ .___/\____/\__/_/\___/____/____/   Spotless CLI
+    /_/
+
+
+Usage: spotless [-hV] [-e=<encoding>] [-l=<lineEnding>] [-m=<spotlessMode>]
+                [-p=N] [-t=<targets>]... [FORMATTING_STEPS]
+Runs spotless
+  -e, --encoding=<encoding>
+                           The encoding of the files to format.
+                             (default: UTF-8)
+  -h, --help               Show this help message and exit.
+  -l, --line-ending=<lineEnding>
+                           The line ending of the files to format.
+                             One of: GIT_ATTRIBUTES,
+                             GIT_ATTRIBUTES_FAST_ALLSAME, PLATFORM_NATIVE,
+                             WINDOWS, UNIX, MAC_CLASSIC, PRESERVE
+                             (default: UNIX)
+  -m, --mode=<spotlessMode>
+                           The mode to run spotless in.
+                             One of: CHECK, APPLY
+                             (default: APPLY)
+  -p, --parallelity=N      The number of parallel formatter threads to run.
+                             (default: #cores * 0.5)
+  -t, --target=<targets>   The target files to format.
+  -V, --version            Print version information and exit.
+
+Available formatting steps:
+  license-header      Runs license header
+  google-java-format  Runs google java format
+  prettier            Runs prettier
+```
+
+<!---freshmark /usage_main -->
+
 ## Available Formatter Steps
 
 Spotless CLI supports the following formatter steps in alphabetical order:
@@ -107,7 +155,12 @@ Formats Java files according to the [google-java-format](https://github.com/goog
 
 To see usage instructions for the google-java-format formatter, run: `spotless google-java-format --help`
 
-<!-- TODO implement mechanism to add this text dynamically from the cli (maybe using freshmark) -->
+<!---freshmark usage_google_java_format
+output =
+   '```shell\n' +
+   {{usage.google-java-format.array}}.join('\n') +
+    '\n```';
+-->
 
 ```shell
 Usage: spotless google-java-format [-hijrV] [-s=<style>]
@@ -126,6 +179,8 @@ Runs google java format
   -V, --version           Print version information and exit.
 ```
 
+<!---freshmark /usage_google_java_format -->
+
 Example usage:
 
 ```shell
@@ -138,6 +193,13 @@ Add or update a license header to the files.
 
 To see usage instructions for the license-header formatter, run: `spotless license-header --help`
 
+<!---freshmark usage_license_header
+output =
+   '```shell\n' +
+   {{usage.license-header.array}}.join('\n') +
+    '\n```';
+-->
+
 ```shell
 Usage: spotless license-header [-hV] [-c=<contentPattern>] [-d=<delimiter>]
                                [-m=<yearMode>] [-s=<skipLinesMatching>]
@@ -175,6 +237,8 @@ Runs license header
                             (default: -)
 ```
 
+<!---freshmark /usage_license_header -->
+
 Example usage:
 
 ```shell
@@ -190,6 +254,13 @@ Even more languages can be supported by including [prettier-plugins](https://pre
 
 To see usage instructions for the prettier formatter, run: `spotless prettier --help`
 
+<!---freshmark usage_prettier
+output =
+   '```shell\n' +
+   {{usage.prettier.array}}.join('\n') +
+    '\n```';
+-->
+
 ```shell
 Usage: spotless prettier [-hV] [-C=<cacheDir>] [-n=<explicitNpmExecutable>]
                          [-N=<explicitNodeExecutable>]
@@ -217,6 +288,8 @@ Runs prettier
   -V, --version   Print version information and exit.
 ```
 
+<!---freshmark /usage_prettier -->
+
 Example usage:
 
 ```shell

build-logic/src/main/groovy/buildlogic.spotless-markdown-conventions.gradle

@@ -2,21 +2,69 @@ plugins {
 	id 'buildlogic.spotless-common-conventions'
 }
 
-def versionCatalog = project.extensions.getByType(VersionCatalogsExtension).named("libs")
-def versionsCollected = [:]
-versionCatalog.versionAliases.each {versionAlias ->
-	versionsCollected.put('libs.versions.' + versionAlias, versionCatalog.findVersion(versionAlias).get())
-}
-
 spotless {
 	freshmark {
 		// freshmark for keeping markdown files up to date
 		target '*.md'
 		// provide lib versions to freshmark
-		properties {
-			it.putAll(versionsCollected)
-		}
+		properties(new FreshmarkPropertiesAction(rootProject, project))
 		prettier() // prettier for markdown formatting
 		endWithNewline()
 	}
 }
+
+class FreshmarkPropertiesAction implements Action<Map<String, Object>> {
+
+	private final Project rootProject
+	private final Project project
+
+	FreshmarkPropertiesAction(Project rootProject, Project project) {
+		this.rootProject = rootProject
+		this.project = project
+	}
+
+	@Override
+	void execute(Map<String, Object> properties) {
+		def versionsCollected = getVersionsCollected()
+		properties.putAll(versionsCollected)
+		def usageHelps = getUsageHelps()
+		properties.putAll(usageHelps)
+	}
+
+	Map<String, String> getVersionsCollected() {
+		def versionCatalog = project.extensions.getByType(VersionCatalogsExtension).named("libs")
+		Map<String, String> versionsCollected = [:]
+		versionCatalog.versionAliases.each {versionAlias ->
+			versionsCollected.put('libs.versions.' + versionAlias, versionCatalog.findVersion(versionAlias).get().toString())
+		}
+		return versionsCollected
+	}
+
+	Map<String, String> getUsageHelps() {
+		Map<String, String> usageHelps = [:]
+		File outputDir = rootProject.file("app/build/generated-usages")
+		File[] usageFiles = outputDir.listFiles()
+
+		usageFiles.each { usageFile ->
+			String usage = asJsArrayOfLines(usageFile.readLines())
+			String name = usageFile.name.substring(0, usageFile.name.indexOf('.'))
+			usageHelps.put("usage.${name}.array".toString(), usage)
+		}
+		return usageHelps
+	}
+
+	private static String asJsArrayOfLines(List<String> lines) {
+		return '[' +
+				lines.collect() { line -> "'${jsEscaped(line)}'" }
+				.join(',\n') +
+				']'
+	}
+
+	private static String jsEscaped(String str) {
+		return str.replace('\\', '\\\\').replace("'", "\\'")
+	}
+}
+
+tasks.named('spotlessFreshmark').configure {
+	dependsOn(':app:generateUsage') // to make sure usage files are generated before spotlessFreshmark
+}