Generate docs for CLI flags

Makefile

@@ -7,7 +7,7 @@ develop:
 	hugo server \
         --buildDrafts \
         --buildFuture \
-        --disableFastRender
+	--ignoreCache
 
 clean:
 	rm -rf public
@@ -17,7 +17,6 @@ build-content:
 
 build: clean build-content
 
-
 htmlproofer-setup:
 	gem install bundler
 	NOKOGIRI_USE_SYSTEM_LIBRARIES=true bundle install \

README.md

@@ -42,8 +42,19 @@ Diagrams included in the documentation are created in the shared [Google Slides
 
 Each Jaeger version is documented in a separate directory e.g. [content/docs/1.8/](./content/docs/1.8/). A special directory [content/docs/next-release/](./content/docs/next-release/) is reserved for the changes to be published as the next version. If you are adding documentation for features that are not yet released in the main Jaeger repository, add your changes to the `next-release` directory. If you're adding documentation for already released features, you may need to make the same change twice, i.e. in the most recent release (e.g. `1.8`) and in the `next-release` directories.
 
-Before creating a new release, make sure all outstanding PRs for that version are merged to `next-release` directory.
-Then create a release by pushing a tag `release-X.Y.Z`, ex `git tag release-1.12.0; git push origin release-1.12.0`.
+Before creating a new release, make sure all outstanding PRs for that version are merged to `next-release` directory. Then create a release by pushing a tag `release-X.Y.Z`, ex `git tag release-1.12.0; git push origin release-1.12.0`.
+
+Note: next release automation currently does not include generation of CLI flag docs.
+
+### Auto-generated documentation for CLI flags
+
+The docs for the Jaeger CLI tools are generated using the `docs` command with their respective Docker images, automated with the following script:
+
+```bash
+python ./scripts/gen-cli-data.py ${VERSION_MAJOR_MINOR}
+```
+
+The script requires `data/cli/${VERSION}/config.json` file that describes the binaries and their storage options. When cutting a new release this file should be copied from the previous release, and adjusted as needed (e.g. if new storage option is implemented). The script generates YAML files in `data/cli/${VERSION}` directory.
 
 ## License
 

content/docs/1.13/cli.md

@@ -0,0 +1,12 @@
+---
+title: CLI flags
+widescreen: true
+---
+
+This is auto-generated documentation for CLI flags supported by Jaeger binaries.
+
+  * CLI flags for some binaries change depending on the `SPAN_STORAGE_TYPE` environment variable. Relevant variations are included below.
+  * Some binaries support _commands_ (mostly informational), such as `env`, `docs`, and `version`. These commands are not included here.
+  * All parameters can be also provided via environment variables, by changing all letters to upper-case and replacing all punctuation characters with underscore `_`. For example, the value for the flag `--cassandra.connections-per-host` can be  provided via `CASSANDRA_CONNECTIONS_PER_HOST` environment variable.
+
+{{< cli/tools-list >}}

data/cli/1.13/config.json

@@ -0,0 +1,43 @@
+{
+    "tools": [
+        "jaeger-all-in-one",
+        "jaeger-agent",
+        "jaeger-collector",
+        "jaeger-ingester",
+        "jaeger-query"      
+    ],
+    "jaeger-all-in-one": {
+        "storage": [
+            "cassandra",
+            "elasticsearch",
+            "memory",
+            "badger",
+            "grpc-plugin"
+        ]
+    },
+    "jaeger-collector": {
+        "storage": [
+            "cassandra",
+            "elasticsearch",
+            "kafka",
+            "grpc-plugin"
+        ]
+    },
+    "jaeger-ingester": {
+        "storage": [
+            "cassandra",
+            "elasticsearch",
+            "grpc-plugin"
+        ]
+    },
+    "jaeger-query": {
+        "storage": [
+            "cassandra",
+            "elasticsearch",
+            "grpc-plugin"
+        ]
+    },
+    "jaeger-agent": {
+        "storage": []
+    }
+}

data/cli/1.13/jaeger-agent.yaml

@@ -0,0 +1,120 @@
+name: jaeger-agent
+synopsis: |
+  Jaeger agent is a local daemon program which collects tracing data.
+description: |
+  Jaeger agent is a daemon program that runs on every host and receives tracing data submitted by Jaeger client libraries.
+options:
+- name: admin-http-port
+  default_value: "14271"
+  usage: |
+    The http port for the admin server, including health check, /metrics, etc.
+- name: collector.host-port
+  usage: (deprecated) see --reporter.tchannel.host-port
+- name: config-file
+  usage: |
+    Configuration file in JSON, TOML, YAML, HCL, or Java properties formats (default none). See spf13/viper for precedence.
+- name: discovery.conn-check-timeout
+  default_value: 250ms
+  usage: |
+    (deprecated) see --reporter.tchannel.discovery.conn-check-timeout
+- name: discovery.min-peers
+  default_value: "3"
+  usage: (deprecated) see --reporter.tchannel.discovery.min-peers
+- name: health-check-http-port
+  default_value: "0"
+  usage: (deprecated) see --admin-http-port
+- name: help
+  shorthand: h
+  default_value: "false"
+  usage: help for jaeger-agent
+- name: http-server.host-port
+  default_value: :5778
+  usage: |
+    host:port of the http server (e.g. for /sampling point and /baggageRestrictions endpoint)
+- name: jaeger.tags
+  usage: |
+    One or more tags to be added to the Process tags of all spans passing through this agent. Ex: key1=value1,key2=${envVar:defaultValue}
+- name: log-level
+  default_value: info
+  usage: |
+    Minimal allowed log Level. For more levels see https://github.com/uber-go/zap
+- name: metrics-backend
+  default_value: prometheus
+  usage: |
+    Defines which metrics backend to use for metrics reporting: expvar, prometheus, none
+- name: metrics-http-route
+  default_value: /metrics
+  usage: |
+    Defines the route of HTTP endpoint for metrics backends that support scraping
+- name: processor.jaeger-binary.server-host-port
+  default_value: :6832
+  usage: host:port for the UDP server
+- name: processor.jaeger-binary.server-max-packet-size
+  default_value: "65000"
+  usage: max packet size for the UDP server
+- name: processor.jaeger-binary.server-queue-size
+  default_value: "1000"
+  usage: length of the queue for the UDP server
+- name: processor.jaeger-binary.workers
+  default_value: "10"
+  usage: how many workers the processor should run
+- name: processor.jaeger-compact.server-host-port
+  default_value: :6831
+  usage: host:port for the UDP server
+- name: processor.jaeger-compact.server-max-packet-size
+  default_value: "65000"
+  usage: max packet size for the UDP server
+- name: processor.jaeger-compact.server-queue-size
+  default_value: "1000"
+  usage: length of the queue for the UDP server
+- name: processor.jaeger-compact.workers
+  default_value: "10"
+  usage: how many workers the processor should run
+- name: processor.zipkin-compact.server-host-port
+  default_value: :5775
+  usage: host:port for the UDP server
+- name: processor.zipkin-compact.server-max-packet-size
+  default_value: "65000"
+  usage: max packet size for the UDP server
+- name: processor.zipkin-compact.server-queue-size
+  default_value: "1000"
+  usage: length of the queue for the UDP server
+- name: processor.zipkin-compact.workers
+  default_value: "10"
+  usage: how many workers the processor should run
+- name: reporter.grpc.discovery.min-peers
+  default_value: "3"
+  usage: |
+    Max number of collectors to which the agent will try to connect at any given time
+- name: reporter.grpc.host-port
+  usage: |
+    Comma-separated string representing host:port of a static list of collectors to connect to directly.
+- name: reporter.grpc.retry.max
+  default_value: "3"
+  usage: Sets the maximum number of retries for a call.
+- name: reporter.grpc.tls
+  default_value: "false"
+  usage: Enable TLS.
+- name: reporter.grpc.tls.ca
+  usage: Path to a TLS CA file. (default use the systems truststore)
+- name: reporter.grpc.tls.server-name
+  usage: Override the TLS server name.
+- name: reporter.tchannel.discovery.conn-check-timeout
+  default_value: 250ms
+  usage: sets the timeout used when establishing new connections
+- name: reporter.tchannel.discovery.min-peers
+  default_value: "3"
+  usage: |
+    if using service discovery, the min number of connections to maintain to the backend
+- name: reporter.tchannel.host-port
+  usage: |
+    comma-separated string representing host:ports of a static list of collectors to connect to directly (e.g. when not using service discovery)
+- name: reporter.tchannel.report-timeout
+  default_value: 1s
+  usage: sets the timeout used when reporting spans
+- name: reporter.type
+  default_value: grpc
+  usage: Reporter type to use e.g. grpc, tchannel
+see_also:
+- docs - Generates documentation
+- version - Print the version.