-
Notifications
You must be signed in to change notification settings - Fork 158
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add metrics storage support to auto-generated CLI documentation #539
Add metrics storage support to auto-generated CLI documentation #539
Conversation
Signed-off-by: albertteoh <see.kwang.teoh@gmail.com>
Signed-off-by: albertteoh <see.kwang.teoh@gmail.com>
Signed-off-by: albertteoh <see.kwang.teoh@gmail.com>
Signed-off-by: albertteoh <see.kwang.teoh@gmail.com>
<li> | ||
<a href="#{{ $file }}"> | ||
{{ $tool }} with <code>{{ $storage }}</code> | ||
{{ $tool }} with <code>{{ $sampling }}</code> sampling |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Before: "... with adaptive"
After: "... with adaptive sampling"
@@ -80,11 +96,25 @@ <h3 id="{{ $file }}"> | |||
|
|||
<!-- TODO right sidebar gets too long, we should use tabs here --> | |||
<h3 id="{{ $file }}"> | |||
{{ $tool }} with <code>{{ $sampling }}</code> sampling type | |||
{{ $tool }} with <code>{{ $sampling }}</code> sampling |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Before: "... with adaptive sampling type"
After: "... with adaptive sampling"
|
||
|
||
for tool in cfg['tools']: | ||
tool_cfg = cfg[tool] | ||
storage_types=tool_cfg['storage'] | ||
sampling_types=tool_cfg['sampling'] | ||
if storage_types: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
These if
s were redundant as a "zero" value of a list just means the body of the for
loop won't be executed.
# generate generates the CLI documentation for a given "tool" (e.g. | ||
# jaeger-collector, jaeger-query, etc.) and feature (e.g. storage=elasticsearch, | ||
# sampling=adaptive, metrics-storage=prometheus). | ||
def generate(tool, **kwargs): |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think using kwargs
would be simpler and cleaner than adding another "optional" parameter to support metrics storage, especially avoiding the need to extend the storageOrSampling
variable.
I think we need to rethink the organization of this doc. Each entry repeats a lot of options not related to the given storage type. It was sort of ok when there was only one dimension we could vary, now we have three. What if we had a "core flags" section first and then each storage type would only list additional flags it enables? Could we isolate those extra flags by a common prefix? |
For this PR, or for the future? Should I wait on this one to release the new docs for 1.29.0? |
Well, I guess since we're right in the middle of the release we should merge this as is and refactor later. |
I agree that the page has a lot of duplicated flags; I'd originally thought that was by design so all possible flags are localised to that particular configuration to avoid jumping around different sections of the document. I've created a follow-up ticket to discuss and/or address this concern: #541 |
Signed-off-by: albertteoh see.kwang.teoh@gmail.com
Which problem is this PR solving?
Short description of the changes
Testing
Generated CLI docs against version 1.28 to allow output comparison.
Copied generated doc files to
documentation/data/cli/1.28/
and ranmake develop
. The following are relevant screenshots of the rendered changes made in this PR: