Add escaping for links and headers in docsgen #2330
Conversation
ilyakuz-db
requested review from
pietern,
andrewnester,
shreyas-goenka and
denik
as code owners
ilyakuz-db
temporarily deployed
to
test-trigger-is
GitHub Actions
Inactive
| func getDescription(s *jsonschema.Schema, allowMarkdown bool) string { | ||
| if allowMarkdown && s.MarkdownDescription != "" { | ||
| func getDescription(s *jsonschema.Schema) string { | ||
| if s.MarkdownDescription != "" { |
There was a problem hiding this comment.
This was an old workaround which is not needed anymore
| @@ -414,16 +414,6 @@ github.com/databricks/cli/bundle/config/resources.Permission: | |||
| "user_name": | |||
| "description": |- | |||
| The name of the user that has the permission set in level. | |||
| github.com/databricks/cli/bundle/config/resources.Pipeline: | |||
There was a problem hiding this comment.
These fields are already defined in annotations_openapi_overrides.yml
There was a problem hiding this comment.
Could we test that we don't have duplicate entries?
| s = strings.ReplaceAll(s, "<", "\\<") | ||
| s = strings.ReplaceAll(s, ">", "\\>") | ||
| return s | ||
| } |
There was a problem hiding this comment.
Can you include a few tests with cases that you need to address as examples?
The replacements look quite broad. Are these characters categorically rejected?
There was a problem hiding this comment.
The replacements look quite broad. Are these characters categorically rejected?
URL validation is failing because the framework is trying to treat these characters as HTML tag brackets. In runtime it seemed to work when I tested
New docs framework seems to enforce this, so it doesn't work even at the build level
ilyakuz-db
temporarily deployed
to
test-trigger-is
GitHub Actions
Inactive
| @@ -43,7 +43,7 @@ artifacts: | |||
|
|
|||
| * - `files` | |||
| - Sequence | |||
| - The source files for the artifact. See [_](#artifacts.<name>.files). | |||
| - The source files for the artifact. See [_](#artifactsnamefiles). | |||
There was a problem hiding this comment.
Does the docs backend produce these anchor names?
If so it would be good to call this out in the function that strips the characters. And as a side note, are there additional characters that it strips if this is indeed the case?
There was a problem hiding this comment.
Does the docs backend produce these anchor names?
Yes, it is produced like this in resulting HTML by docs framework (it's not exactly backend but build-tool), I'll add a note
And as a side note, are there additional characters that it strips if this is indeed the case?
Probably but we don't expect any weird symbols in our links/titles because all of these are field names from config. The only exceptions are these fancy brackets that we add for <name>
We have URL validation in docs CI that catch any mismatch so I wouldn't strip anything until necessary, at least until framework migration is finished
| @@ -414,16 +414,6 @@ github.com/databricks/cli/bundle/config/resources.Permission: | |||
| "user_name": | |||
| "description": |- | |||
| The name of the user that has the permission set in level. | |||
| github.com/databricks/cli/bundle/config/resources.Pipeline: | |||
There was a problem hiding this comment.
Could we test that we don't have duplicate entries?
ilyakuz-db
temporarily deployed
to
test-trigger-is
GitHub Actions
Inactive
Changes
To avoid build warnings and errors in docs build we need to escape symbols that are treated as syntax elements
Tests