Auto-generate jaeger-v2 config docs via AST

[yurishkuro]

Which problem is this PR solving?

• [experiment] Auto-generate documentation for jaeger-v2 configuration structs via AST #6628

Description of the changes

How was this change tested?

Checklist

• I have read https://github.com/jaegertracing/jaeger/blob/master/CONTRIBUTING_GUIDELINES.md
• I have signed all commits
• I have added unit tests for the new functionality
• I have run lint and test steps successfully
  • for jaeger: make lint test
  • for jaeger-ui: npm run lint and npm run test

[codecov]

Codecov Report

Attention: Patch coverage is 86.05769% with 58 lines in your changes missing coverage. Please review.

Project coverage is 95.83%. Comparing base (24554cf) to head (b06a1e2).

Files with missing lines	Patch %	Lines
cmd/jaeger/internal/configschema/generate.go	81.45%	35 Missing and 16 partials ⚠️
cmd/jaeger/internal/configschema/traverse.go	94.44%	4 Missing and 3 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #7064      +/-   ##
==========================================
- Coverage   96.05%   95.83%   -0.22%     
==========================================
  Files         355      358       +3     
  Lines       20995    21411     +416     
==========================================
+ Hits        20166    20519     +353     
- Misses        624      667      +43     
- Partials      205      225      +20     

Flag	Coverage Δ
badger_v1	9.96% <ø> (ø)
badger_v2	2.06% <ø> (ø)
cassandra-4.x-v1-manual	14.99% <ø> (ø)
cassandra-4.x-v2-auto	2.05% <ø> (ø)
cassandra-4.x-v2-manual	2.05% <ø> (ø)
cassandra-5.x-v1-manual	14.99% <ø> (ø)
cassandra-5.x-v2-auto	2.05% <ø> (ø)
cassandra-5.x-v2-manual	2.05% <ø> (ø)
elasticsearch-6.x-v1	19.93% <ø> (ø)
elasticsearch-7.x-v1	20.01% <ø> (ø)
elasticsearch-8.x-v1	20.18% <ø> (ø)
elasticsearch-8.x-v2	2.06% <ø> (ø)
grpc_v1	11.52% <ø> (ø)
grpc_v2	2.06% <ø> (ø)
kafka-3.x-v1	10.24% <ø> (ø)
kafka-3.x-v2	2.06% <ø> (ø)
memory_v2	2.06% <ø> (ø)
opensearch-1.x-v1	20.06% <ø> (ø)
opensearch-2.x-v1	20.06% <ø> (ø)
opensearch-2.x-v2	2.06% <ø> (ø)
query	2.06% <ø> (ø)
tailsampling-processor	0.56% <ø> (ø)
unittests	94.62% <86.05%> (-0.20%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[AnmolxSingh]

Hi @yurishkuro
I worked on this issue before so I thought of reviewing this pr what I did wrong.
I think the command here for generating .md file does not work for me here. When I generated the .md file I simply used
jsonschema2md cmd/jaeger/internal/configdocs/cmd/jaeger-config-schema.json cmd/jaeger/docs/migration/configdocs.md

I may be missing something please correct me if I am wrong

[yurishkuro]

it doesn't work for me either at the moment. Which jsonschema2md did you use?

[yurishkuro]

but the reason this fails in the PR is because the generated schema is just wrong, it has dangling references.

[AnmolxSingh]

it doesn't work for me either at the moment. Which jsonschema2md did you use?

I used
https://github.com/RalfG/jsonschema2md?tab=readme-ov-file

[AnmolxSingh]

Does Jaeger community has a preference towards any jsonschema2md tool like adobe or any implementation is fine as long as the output is correct?

[yurishkuro]

We want stable and maintained dependencies. RalfG/jsonschema2md is already archived.

[yurishkuro]

I worked on this issue before so I thought of reviewing this pr what I did wrong.

any conclusions? :-) I think the path forward to completion is pretty clear, but requires time investment, which I may not have. The main logic is currently broken, because the schema is generated in an invalid state, with dangling references, some types which are structs in Go are listed as string type, etc. This is why it's useful to start with unit tests, to validate assumptions and edge cases.

[AnmolxSingh]

We want stable and maintained dependencies. RalfG/jsonschema2md is already archived.

actually it is maintained by its fork https://github.com/sbrunner/jsonschema2md

[AnmolxSingh]

I worked on this issue before so I thought of reviewing this pr what I did wrong.

any conclusions? :-) I think the path forward to completion is pretty clear, but requires time investment, which I may not have. The main logic is currently broken, because the schema is generated in an invalid state, with dangling references, some types which are structs in Go are listed as string type, etc. This is why it's useful to start with unit tests, to validate assumptions and edge cases.

Thanks for the feedback, Yuri.
I'm currently working on the "restoring metrics" issue, and as you mentioned, this issue requires time. I’d like to continue focusing on that issue for now. I believe this issue can be resolved, and it might be best for someone else to take over.
Thanks for your understanding!