feat: Config reference documentation autogeneration #2033
Conversation
ilyakuz-db
temporarily deployed
to
test-trigger-is
GitHub Actions
Inactive
ilyakuz-db
temporarily deployed
to
test-trigger-is
GitHub Actions
Inactive
ilyakuz-db
temporarily deployed
to
test-trigger-is
GitHub Actions
Inactive
ilyakuz-db
temporarily deployed
to
test-trigger-is
GitHub Actions
Inactive
ilyakuz-db
temporarily deployed
to
test-trigger-is
GitHub Actions
Inactive
ilyakuz-db
temporarily deployed
to
test-trigger-is
GitHub Actions
Inactive
|
Test Details: go/deco-tests/12401106836 |
ilyakuz-db
requested review from
pietern,
andrewnester,
shreyas-goenka and
denik
as code owners
|
If integration tests don't run automatically, an authorized user can run them manually by following the instructions below: Trigger: Inputs:
Checks will be approved automatically on success. |
ilyakuz-db
temporarily deployed
to
test-trigger-is
GitHub Actions
Inactive
ilyakuz-db
temporarily deployed
to
test-trigger-is
GitHub Actions
Inactive
ilyakuz-db
temporarily deployed
to
test-trigger-is
GitHub Actions
Inactive
ilyakuz-db
temporarily deployed
to
test-trigger-is
GitHub Actions
Inactive
ilyakuz-db
changed the title
bundle/internal/docs/markdown.go
Outdated
| md "github.com/nao1215/markdown" | ||
| ) | ||
|
|
||
| const ( |
There was a problem hiding this comment.
These templates are in this repo temporary to simplify the process of docs updating
This can be further improved by using include declarations in doc repo so we could generate only meaningful part here and store the wrapper file in docs repo
ilyakuz-db
temporarily deployed
to
test-trigger-is
GitHub Actions
Inactive
|
@pietern @shreyas-goenka @andrewnester this one is ready for review if anyone want to take a look! More content updates to annotations will be introduced in follow-up PRs |
bundle/internal/docs/nodes.go
Outdated
| return isCustomField | ||
| } | ||
|
|
||
| func extractNodes(prefix string, props map[string]*jsonschema.Schema, refs map[string]jsonschema.Schema, customFields map[string]bool) []rootProp { |
bundle/internal/docs/refs.go
Outdated
| return true | ||
| } | ||
|
|
||
| func resolveAdditionaProperties(v *jsonschema.Schema) *jsonschema.Schema { |
| return nodes[i].Title < nodes[j].Title | ||
| }) | ||
| return nodes | ||
| } |
There was a problem hiding this comment.
It's very hard to tell what this function does and how it is supposed to work. Please include a few more comments with how you expect it to work, and if possible even a testcase or two to make sure it does work the way you assume. As is we need to run it and check the output to confirm this.
There was a problem hiding this comment.
Added few test cases and re-arranged the code with more comments to highlight important parts
You mean to remove from |
| schema: | ||
| go run ./bundle/internal/schema ./bundle/internal/schema ./bundle/schema/jsonschema.json | ||
|
|
||
| docs: vendor |
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
I mean the make entry should be:
docs:
...
no dependency on vendor
There was a problem hiding this comment.
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 ....
| schema: | ||
| go run ./bundle/internal/schema ./bundle/internal/schema ./bundle/schema/jsonschema.json | ||
|
|
||
| docs: vendor | ||
| go run ./bundle/internal/docs ./bundle/internal/schema ./bundle/internal/docs |
There was a problem hiding this comment.
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
There was a problem hiding this comment.
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
Changes
Documentation autogeneration tool. This tool uses same annotations_*.yml files as in json-schema
Result will go there and there
Tests
Manually