650 ascii doc (#737)

* Add ascii doc generating task

* Generate ascii doc

* Fix line spacing in cli descriptions

release_notes.md

@@ -1,4 +1,5 @@
 ## next (unreleased)
+- [#737](https://github.com/Flank/flank/pull/737) Generate ascii doc. ([jan-gogo](https://github.com/jan-gogo))
 - [#720](https://github.com/Flank/flank/pull/720) Update group id from `flank` to `com.github.flank` ([bootstraponline](https://github.com/bootstraponline))
 - [#714](https://github.com/Flank/flank/pull/714) Add support for num-uniform-shards option. ([jan-gogo](https://github.com/jan-gogo))
 - [#712](https://github.com/Flank/flank/pull/712) Add keep file path for ios. ([pawelpasterz](https://github.com/pawelpasterz))

test_runner/build.gradle.kts

@@ -143,9 +143,6 @@ tasks.withType<KotlinCompile>().configureEach {
     kotlinOptions.allWarningsAsErrors = runningOnBitrise
 }
 
-apply {
-    plugin("kotlin")
-}
 
 application {
     mainClassName = "ftl.Main"
@@ -194,6 +191,7 @@ dependencies {
     implementation(Libs.LOGBACK)
 
     implementation(Libs.PICOCLI)
+    annotationProcessor(Libs.PICOCLI_CODEGEN)
 
     implementation(Libs.WOODSTOX)
 
@@ -237,3 +235,26 @@ tasks.create("updateFlank", Exec::class.java) {
     description = "Update flank jar"
     commandLine = listOf("./bash/update_flank.sh")
 }
+
+// begin --- ASCII doc generation ---
+val generateManpageAsciiDoc by tasks.registering(JavaExec::class) {
+    dependsOn(tasks.classes)
+    classpath(
+        configurations.compile,
+        configurations.annotationProcessor,
+        sourceSets["main"].runtimeClasspath
+    )
+    group = "Documentation"
+    description = "Generate AsciiDoc manpage"
+    main = "picocli.codegen.docgen.manpage.ManPageGenerator"
+    args = listOf(
+        application.mainClassName,
+        "--outdir=${project.rootDir}/docs/ascii/",
+        "-v"
+    )
+}
+
+tasks.assemble {
+    dependsOn(generateManpageAsciiDoc)
+}
+// end --- ASCII doc generation ---

test_runner/buildSrc/src/main/kotlin/Deps.kt

@@ -24,7 +24,7 @@ object Versions {
     const val KOTLIN_COROUTINES = "1.3.2"
 
     // https://github.com/remkop/picocli/releases
-    const val PICOCLI = "4.0.4"
+    const val PICOCLI = "4.2.0"
 
     // https://search.maven.org/search?q=a:google-api-services-toolresults%20g:com.google.apis
     const val GOOGLE_API_TOOLRESULTS = "v1beta3-rev20190923-1.30.3"
@@ -118,6 +118,7 @@ object Libs {
     const val JUNIT = "junit:junit:${Versions.JUNIT}"
     const val OKHTTP = "com.squareup.okhttp3:okhttp:${Versions.OKHTTP}"
     const val PICOCLI = "info.picocli:picocli:${Versions.PICOCLI}"
+    const val PICOCLI_CODEGEN = "info.picocli:picocli-codegen:${Versions.PICOCLI}"
     const val SYSTEM_RULES = "com.github.stefanbirkner:system-rules:${Versions.SYSTEM_RULES}"
     const val TRUTH = "com.google.truth:truth:${Versions.TRUTH}"
     const val MOCKK = "io.mockk:mockk:${Versions.MOCKK}"

test_runner/docs/ascii/flank.jar_-android-doctor.adoc

@@ -0,0 +1,52 @@
+// tag::picocli-generated-full-manpage[]
+// tag::picocli-generated-man-section-header[]
+:doctype: manpage
+:revnumber: 
+:manmanual: Flank.jar
+ Manual
+:mansource: 
+:man-linkstyle: pass:[blue R < >]
+= flank.jar
+-android-doctor(1)
+
+// end::picocli-generated-man-section-header[]
+
+// tag::picocli-generated-man-section-name[]
+== Name
+
+flank.jar
+-android-doctor - Verifies flank firebase is setup correctly
+
+// end::picocli-generated-man-section-name[]
+
+// tag::picocli-generated-man-section-synopsis[]
+== Synopsis
+
+*flank.jar
+ android doctor* [*-fh*] [*-c*=_<configPath>_]
+
+// end::picocli-generated-man-section-synopsis[]
+
+// tag::picocli-generated-man-section-description[]
+== Description
+
+Validates Android Flank YAML.
+
+
+// end::picocli-generated-man-section-description[]
+
+// tag::picocli-generated-man-section-options[]
+== Options
+
+*-c*, *--config*=_<configPath>_::
+  YAML config file path
+
+*-h*, *--help*::
+  Prints this help message
+
+*-f*, *--fix*::
+  Auto fix flank YAML file
+
+// end::picocli-generated-man-section-options[]
+
+// end::picocli-generated-full-manpage[]

test_runner/docs/ascii/flank.jar_-android-run.adoc

@@ -0,0 +1,215 @@
+// tag::picocli-generated-full-manpage[]
+// tag::picocli-generated-man-section-header[]
+:doctype: manpage
+:revnumber: 
+:manmanual: Flank.jar
+ Manual
+:mansource: 
+:man-linkstyle: pass:[blue R < >]
+= flank.jar
+-android-run(1)
+
+// end::picocli-generated-man-section-header[]
+
+// tag::picocli-generated-man-section-name[]
+== Name
+
+flank.jar
+-android-run - Run tests on Firebase Test Lab
+
+// end::picocli-generated-man-section-name[]
+
+// tag::picocli-generated-man-section-synopsis[]
+== Synopsis
+
+*flank.jar
+ android run* [*-h*] [*--async*] [*--auto-google-login*]
+                       [*--disable-sharding*] [*--dry*] [*--dump-shards*]
+                       [*--ignore-failed-tests*] [*--keep-file-path*]
+                       [*--legacy-junit-result*] [*--no-auto-google-login*]
+                       [*--no-performance-metrics*] [*--no-record-video*]
+                       [*--no-use-orchestrator*] [*--performance-metrics*]
+                       [*--record-video*] [*--smart-flank-disable-upload*]
+                       [*--use-orchestrator*] [*--app*=_<app>_] [*-c*=_<configPath>_]
+                       [*--local-result-dir*=_<localResultsDir>_]
+                       [*--max-test-shards*=_<maxTestShards>_]
+                       [*--network-profile*=_<networkProfile>_]
+                       [*--num-flaky-test-attempts*=_<flakyTestAttempts>_]
+                       [*--num-test-runs*=_<repeatTests>_]
+                       [*--num-uniform-shards*=_<numUniformShards>_]
+                       [*--project*=_<project>_] [*--results-bucket*=_<resultsBucket>_]
+                       [*--results-dir*=_<resultsDir>_]
+                       [*--results-history-name*=_<resultsHistoryName>_]
+                       [*--run-timeout*=_<runTimeout>_] [*--shard-time*=_<shardTime>_]
+                       [*--smart-flank-gcs-path*=_<smartFlankGcsPath>_]
+                       [*--test*=_<test>_] [*--test-runner-class*=_<testRunnerClass>_]
+                       [*--timeout*=_<timeout>_] [*--additional-apks*=_<additionalApks>_
+                       [,_<additionalApks>_...]]...
+                       [*--additional-app-test-apks*=_<String=String>_[,
+                       _<String=String>_...]]... [*--client-details*=_<String=String>_
+                       [,_<String=String>_...]]... [*--device*=_<String=String>_[,
+                       _<String=String>_...]]...
+                       [*--directories-to-pull*=_<directoriesToPull>_[,
+                       _<directoriesToPull>_...]]...
+                       [*--environment-variables*=_<String=String>_[,
+                       _<String=String>_...]]...
+                       [*--files-to-download*=_<filesToDownload>_[,
+                       _<filesToDownload>_...]]... [*--other-files*=_<String=String>_
+                       [,_<String=String>_...]]... [*--test-targets*=_<testTargets>_[,
+                       _<testTargets>_...]]...
+                       [*--test-targets-always-run*=_<testTargetsAlwaysRun>_[,
+                       _<testTargetsAlwaysRun>_...]]...
+
+// end::picocli-generated-man-section-synopsis[]
+
+// tag::picocli-generated-man-section-description[]
+== Description
+
+Uploads the app and test apk to GCS.
+Runs the espresso tests using orchestrator.
+Configuration is read from flank.yml
+
+
+// end::picocli-generated-man-section-description[]
+
+// tag::picocli-generated-man-section-options[]
+== Options
+
+*--dry*::
+  Dry run on mock server
+
+*-h*, *--help*::
+  Prints this help message
+
+*--run-timeout*=_<runTimeout>_::
+  The max time this test run can execute before it is cancelled (default: unlimited).
+
+*--results-bucket*=_<resultsBucket>_::
+  The name of a Google Cloud Storage bucket where raw test results will be stored (default: "test-lab-<random-UUID>"). Note that the bucket must be owned by a billing-enabled project, and that using a non-default bucket will result in billing charges for the storage used.
+
+*--results-dir*=_<resultsDir>_::
+  The name of a unique Google Cloud Storage object within the results bucket where raw test results will be stored (default: a timestamp with a random suffix). Caution: if specified, this argument must be unique for each test matrix you create, otherwise results from multiple test matrices will be overwritten or intermingled.
+
+*--record-video*::
+  Enable video recording during the test. Disabled by default.
+
+*--no-record-video*::
+  Disable video recording during the test (default behavior). Use --record-video to enable.
+
+*--timeout*=_<timeout>_::
+  The max time this test execution can run before it is cancelled (default: 15m). It does not include any time necessary to prepare and clean up the target device. The maximum possible testing time is 30m on physical devices and 60m on virtual devices. The TIMEOUT units can be h, m, or s. If no unit is given, seconds are assumed. 
+
+*--async*::
+  Invoke a test asynchronously without waiting for test results.
+
+*--client-details*=_<String=String>_[,_<String=String>_...]::
+  Comma-separated, KEY=VALUE map of additional details to attach to the test matrix.Arbitrary KEY=VALUE pairs may be attached to a test matrix to provide additional context about the tests being run.When consuming the test results, such as in Cloud Functions or a CI system,these details can add additional context such as a link to the corresponding pull request.
+
+*--network-profile*=_<networkProfile>_::
+  The name of the network traffic profile, for example --network-profile=LTE, which consists of a set of parameters to emulate network conditions when running the test (default: no network shaping; see available profiles listed by the `flank test network-profiles list` command). This feature only works on physical devices. 
+
+*--results-history-name*=_<resultsHistoryName>_::
+  The history name for your test results (an arbitrary string label; default: the application's label from the APK manifest). All tests which use the same history name will have their results grouped together in the Firebase console in a time-ordered test history list.
+
+*--num-flaky-test-attempts*=_<flakyTestAttempts>_::
+  The number of times a TestExecution should be re-attempted if one or more of its test cases fail for any reason. The maximum number of reruns allowed is 10. Default is 0, which implies no reruns.
+
+*--max-test-shards*=_<maxTestShards>_::
+  The amount of matrices to split the tests across.
+
+*--shard-time*=_<shardTime>_::
+  The max amount of seconds each shard should run.
+
+*--num-test-runs*=_<repeatTests>_::
+  The amount of times to run the test executions.
+
+*--smart-flank-gcs-path*=_<smartFlankGcsPath>_::
+  Google cloud storage path to save test timing data used by smart flank.
+
+*--smart-flank-disable-upload*::
+  Disables smart flank JUnit XML uploading. Useful for preventing timing data from being updated.
+
+*--disable-sharding*::
+  Disable sharding.
+
+*--test-targets-always-run*=_<testTargetsAlwaysRun>_[,_<testTargetsAlwaysRun>_...]::
+  A list of one or more test methods to always run first in every shard.
+
+*--files-to-download*=_<filesToDownload>_[,_<filesToDownload>_...]::
+  A list of paths that will be downloaded from the resulting bucket to the local results folder after the test is complete. These must be absolute paths (for example, --files-to-download /images/tempDir1,/data/local/tmp/tempDir2). Path names are restricted to the characters a-zA-Z0-9_-./+.
+
+*--project*=_<project>_::
+  The Google Cloud Platform project name to use for this invocation. If omitted, then the project from the service account credential is used
+
+*--local-result-dir*=_<localResultsDir>_::
+  Saves test result to this local folder. Deleted before each run.
+
+*--ignore-failed-tests*::
+  Terminate with exit code 0 when there are failed tests. Useful for Fladle and other gradle plugins that don't expect the process to have a non-zero exit code. The JUnit XML is used to determine failure. (default: false)
+
+*--keep-file-path*::
+  Keeps the full path of downloaded files. Required when file names are not unique.
+
+*--dump-shards*::
+  Dumps the shards to android_shards.json for debugging
+
+*-c*, *--config*=_<configPath>_::
+  YAML config file path
+
+*--app*=_<app>_::
+  The path to the application binary file. The path may be in the local filesystem or in Google Cloud Storage using gs:// notation.
+
+*--test*=_<test>_::
+  The path to the binary file containing instrumentation tests. The given path may be in the local filesystem or in Google Cloud Storage using a URL beginning with gs://.
+
+*--additional-apks*=_<additionalApks>_[,_<additionalApks>_...]::
+  A list of up to 100 additional APKs to install, in addition to those being directly tested.The path may be in the local filesystem or in Google Cloud Storage using gs:// notation. 
+
+*--auto-google-login*::
+  Automatically log into the test device using a preconfigured Google account before beginning the test. Disabled by default.
+
+*--no-auto-google-login*::
+  Google account not logged in (default behavior). Use --auto-google-login to enable
+
+*--use-orchestrator*::
+  Whether each test runs in its own Instrumentation instance with the Android Test Orchestrator (default: Orchestrator is used. To disable, use --no-use-orchestrator). Orchestrator is only compatible with AndroidJUnitRunner v1.0 or higher. See https://developer.android.com/training/testing/junit-runner.html#using-android-test-orchestrator for more information about Android Test Orchestrator.
+
+*--no-use-orchestrator*::
+  Orchestrator is not used. See --use-orchestrator.
+
+*--environment-variables*=_<String=String>_[,_<String=String>_...]::
+  A comma-separated, key=value map of environment variables and their desired values. --environment-variables=coverage=true,coverageFile=/sdcard/coverage.ec The environment variables are mirrored as extra options to the am instrument -e KEY1 VALUE1 … command and passed to your test runner (typically AndroidJUnitRunner)
+
+*--directories-to-pull*=_<directoriesToPull>_[,_<directoriesToPull>_...]::
+  A list of paths that will be copied from the device's storage to the designated results bucket after the test is complete. These must be absolute paths under /sdcard or /data/local/tmp (for example, --directories-to-pull /sdcard/tempDir1,/data/local/tmp/tempDir2). Path names are restricted to the characters a-zA-Z0-9_-./+. The paths /sdcard and /data will be made available and treated as implicit path substitutions. E.g. if /sdcard on a particular device does not map to external storage, the system will replace it with the external storage path prefix for that device.
+
+*--other-files*=_<String=String>_[,_<String=String>_...]::
+  A list of device-path=file-path pairs that indicate the device paths to push files to the device before starting tests, and the paths of files to push.Device paths must be under absolute, whitelisted paths (null, or null/local/tmp).Source file paths may be in the local filesystem or in Google Cloud Storage (gs://…). 
+
+*--performance-metrics*::
+  Monitor and record performance metrics: CPU, memory, network usage, and FPS (game-loop only). Disabled by default.
+
+*--no-performance-metrics*::
+  Disables performance metrics (default behavior). Use --performance-metrics to enable.
+
+*--num-uniform-shards*=_<numUniformShards>_::
+  Specifies the number of shards into which you want to evenly distribute test cases.The shards are run in parallel on separate devices. For example,if your test execution contains 20 test cases and you specify four shards, each shard executes five test cases.The number of shards should be less than the total number of test cases.The number of shards specified must be >= 1 and <= 50.This option cannot be used along max-test-shards and is not compatible with smart sharding.If you want to take benefits of smart sharding use max-test-shards.
+
+*--test-runner-class*=_<testRunnerClass>_::
+  The fully-qualified Java class name of the instrumentation test runner (default: the last name extracted from the APK manifest).
+
+*--test-targets*=_<testTargets>_[,_<testTargets>_...]::
+  A list of one or more test target filters to apply (default: run all test targets). Each target filter must be fully qualified with the package name, class name, or test annotation desired. Any test filter supported by am instrument -e … is supported. See https://developer.android.com/reference/android/support/test/runner/AndroidJUnitRunner for more information.
+
+*--legacy-junit-result*::
+  Fallback for legacy xml junit results parsing.
+
+*--device*=_<String=String>_[,_<String=String>_...]::
+  A list of DIMENSION=VALUE pairs which specify a target device to test against. This flag may be repeated to specify multiple devices. The four device dimensions are: model, version, locale, and orientation. If any dimensions are omitted, they will use a default value. Omitting all of the preceding dimension-related flags will run tests against a single device using defaults for all four device dimensions.
+
+*--additional-app-test-apks*=_<String=String>_[,_<String=String>_...]::
+  A list of app & test apks to include in the run. Useful for running multiple module tests within a single Flank run.
+
+// end::picocli-generated-man-section-options[]
+
+// end::picocli-generated-full-manpage[]

test_runner/docs/ascii/flank.jar_-android.adoc

@@ -0,0 +1,48 @@
+// tag::picocli-generated-full-manpage[]
+// tag::picocli-generated-man-section-header[]
+:doctype: manpage
+:revnumber: 
+:manmanual: Flank.jar
+ Manual
+:mansource: 
+:man-linkstyle: pass:[blue R < >]
+= flank.jar
+-android(1)
+
+// end::picocli-generated-man-section-header[]
+
+// tag::picocli-generated-man-section-name[]
+== Name
+
+flank.jar
+-android - 
+
+// end::picocli-generated-man-section-name[]
+
+// tag::picocli-generated-man-section-synopsis[]
+== Synopsis
+
+*flank.jar
+ android* [COMMAND]
+
+// end::picocli-generated-man-section-synopsis[]
+
+// tag::picocli-generated-man-section-description[]
+== Description
+
+
+
+// end::picocli-generated-man-section-description[]
+
+// tag::picocli-generated-man-section-commands[]
+== Commands
+
+*run*::
+  Run tests on Firebase Test Lab
+
+*doctor*::
+  Verifies flank firebase is setup correctly
+
+// end::picocli-generated-man-section-commands[]
+
+// end::picocli-generated-full-manpage[]