WIP: Add flags

[pavolloffay]

Updates #250

Signed-off-by: Pavol Loffay [email protected]

TODOs:

• fix links in See also https://deploy-preview-257--jaegertracing.netlify.com/docs/next-release/jaeger-all-in-one_version/#see-also

[pavolloffay]

The UI menu could have this structure:

* all-in-one
** badger, es?, cassanra?
* agent
* query
** es
* collector
** es
* ingester
** es

EDIT: Or just have a single page per component and put storage differences in different sections/tabs.

[yurishkuro]

Are these pages manually created? Not sure what the plan is here.

I don't think pre-formatted text output is a good format - it's actually harder to read on the web page than by running the help command in a terminal. We'd need tabular format, either markdown or html.

Top level menu item could be Man Pages. Since the left sidebar only supports two levels, the rest of the sub-sections should be in a single md file, and they will show on the right sidebar menu.

[pavolloffay]

The pages are auto-created by docs command in jaegertracing/jaeger#1572.

Manually has to be added menu item at the top of each page, we could do that with sed.

I don't think pre-formatted text output is a good format - it's actually harder to read on the web page than by running the help command in a terminal. We'd need tabular format, either markdown or html.

We want to publish this on the website for people running on k8s or even docker. There is a benefit having it here folks don't have to download and run to find out jaeger supports something.

Any suggestions on the format are welcome. My first objective is to make it work and auto-publish during the release. Once we have that we can reiterate and change the formatting. Sounds good?

[yurishkuro]

My first objective is to make it work and auto-publish during the release. Once we have that we can reiterate and change the formatting.

I don't know, I find documentation that I can't actually read way more annoying than having to run a command. With pre-formatted text the flag descriptions are all on one line that you have to scroll horizontally.

cobra has man-page output format, I changed the PR to:

			header := &doc.GenManHeader{
				Title:   "jaeger-all-in-one",
				Section: "3",
			}
			return doc.GenManTree(cmd, header, "./")

and then converted to plain text

groff -t -e -mandoc -Tascii jaeger-all-in-one-env.3 | col -bx

These are much more readable than the markdown output from cobra.

cobra internally can actually produce normal help output with line wrapping, but the setting is private last time I checked. If we could fix that then both help output would be more readable and it would work as pre-formatted text in .md without scrolling

[pavolloffay]

Hi @lucperkins, could you please have a look at how we could improve styling for generated options https://deploy-preview-257--jaegertracing.netlify.com/docs/next-release/jaeger-query/#options?

I have found that hugo is also using cobra and they publish generated md files https://gohugo.io/commands/hugo/. They just extend the view when you hover the mouse.

[lucperkins]

@pavolloffay I think I'd prefer to have all of the CLI stuff on one page. We could create a YAML file that describes all the commands and flags and then generate pretty HTML out of that. I've done this on other sites, for example in the Apache Pulsar documentation.

I know that you can generate JSON or YAML from Cobra, but I think that the Jaeger CLI has a small enough surface area that we could keep it updated by hand.

[yurishkuro]

I think it's a good idea to drive from yaml and just define our own rendering template.

This is how YAML from cobra looks:

$ m jaeger-query.yaml
name: jaeger-query
synopsis: |
  Jaeger query service provides a Web UI and an API for accessing trace data.
description: |
  Jaeger query service provides a Web UI and an API for accessing trace data.
options:
- name: admin-http-port
  default_value: "16687"
  usage: |
    The http port for the admin server, including health check, /metrics, etc.
- name: cassandra-archive.connections-per-host
  default_value: "0"
  usage: |
    The number of Cassandra connections from a single backend instance

[lucperkins]

@yurishkuro If you can add separate YAML files for each CLI tool into the data directory I can work on templates.

[yurishkuro]

it's actually multiple YAML files for each binary - one file per "command", e.g. "collector help" vs "collector docs", etc. Example attached.

jaeger-query.zip

[pavolloffay]

@lucperkins the doc files can be generated with docker command. The files will be generated in your current working directory:

docker run --rm -it  -v "${PWD}:/data" jaegertracing/jaeger-query:latest docs --format=yaml --dir=/data
docker run --rm -it  -v "${PWD}:/data" jaegertracing/jaeger-collector:latest docs --format=yaml --dir=/data

There are multiple files, each per command e.g. jaeger-query docs, jaeger-query env, jaeger-query version`

jaeger-query.yaml
jaeger-query_docs.yaml
jaeger-query_env.yaml
jaeger-query_version.yaml

There is one more complication. This will show flags only for the default storage (cassandra), but we also need to show flags for other storages - elasticsearch, badger. This can be generated via docker run --rm -it -e SPAN_STORAGE_TYPE=elasticsearch -v "${PWD}:/data" jaegertracing/jaeger-query:latest docs --format=yaml --dir=/data (note that this overrides previous files). The storage variations could be maybe shown as tabs like in istio docs - https://istio.io/docs/setup/kubernetes/install/kubernetes/#installation-steps. The same visualization could be used to distinguish kubernetes and openshift in #258.

EDIT: alternatively we could filter our storage flags and show only them in separate tabs.

[pavolloffay]

@lucperkins have a look here https://deploy-preview-257--jaegertracing.netlify.com/docs/next-release/commands/ how I have done the storage "sections". Note also that this is pretty much the default view we get from docs command. Nice is that pages between commands are cross-linked (SEE ALSO section)

[pavolloffay]

@lucperkins do you want me to create a separate PR with yaml files in data dir or do you prefer generating it yourself?

[yurishkuro]

Done in #266