Autogenerated documentation for bundle config

[ilyakuz-db]

Changes

Documentation autogeneration tool. This tool uses same annotations_*.yml files as in json-schema

Result will go there and there

Tests

Manually

[eng-dev-ecosystem-bot]

Test Details: go/deco-tests/12401106836

[github-actions]

If integration tests don't run automatically, an authorized user can run them manually by following the instructions below:

Trigger:
go/deco-tests-run/cli

Inputs:

• PR number: 2033
• Commit SHA: c6703c13637c0d85e6754e4c802f38052304a5d6

Checks will be approved automatically on success.

[denik]

docs: vendor

We don't add this implicitly anymore to other targets. If you're on CI, you can always specify both with "make vendor docs".

BTW, do you intended to run it on CI?

[ilyakuz-db]

BTW, do you intended to run it on CI?

Currently the only use case of using that tool is to checkout CLI repo and run locally

We don't add this implicitly anymore to other targets

By implicitly you mean using make deps or in general?

[denik]

I mean the make entry should be:

docs:
  ...

no dependency on vendor

[ilyakuz-db]

Could you elaborate little bit more on the reasoning behind "We don't add this implicitly anymore to other targets" so I can understand how to better fix it?

Is it just that we don't want to rely on make deps syntax and this is still allowed?

docs:
  make vendor
  go run ....

[ilyakuz-db]

Removed and update the readme

[denik]

Why is this part if /bundle/internal/ ?

internal is meant for code that is not meant to be used outside of the package, but this is clearly intended to be used outside the package, that's why it's in Makefile.

How about placing this at top level? /docsgen/ ?

I see you're following existing structure, so it's a more of a question for @pietern

[ilyakuz-db]

I see you're following existing structure,

Yes I reused same approach as with json schema generation which is used in .codegen.json along with other internal scripts

[pietern]

This is bundle specific, so bundle/docsgen would be more appropriate.

It doesn't need to be internal.

[ilyakuz-db]

@pietern @denik could you take another look? Want to merge it so docs team could start using this tool

[denik]

This is copied, right?

It would be much easier to review if PRs was split into

• refactoring: copy / renames
• new functionality

[ilyakuz-db]

Yes, this was moved as is from schema package into the new package

[ilyakuz-db]

It would be much easier to review if PRs was split into

refactoring: copy / renames
new functionality

Agree but it feels too painful to split now. For next PRs I'll try to follow more convenient approach

[pietern]

Do you know if the schema check we perform also validates that entries here match the containing schema?

[ilyakuz-db]

I think it only tests yamls against the schema but not the schema consistency itsef

I.e. this is allowed

In general spec says that example values should validate against schema but it isn't used and not required
https://json-schema.org/understanding-json-schema/reference/annotations see draft 6

Worth to mention that this field currently is not used in schema generation

[pietern]

This is bundle specific, so bundle/docsgen would be more appropriate.

It doesn't need to be internal.