docs: Cleanup more literals in API docs#22174
Conversation
|
Docs for this Pull Request will be rendered here: https://storage.googleapis.com/envoy-pr/22174/docs/index.html The docs are (re-)rendered each time the CI |
phlax
force-pushed
the
no-name-config
branch
2 times, most recently
from
578419e to
3e5f92b
Compare
|
CC @envoyproxy/api-shepherds: Your approval is needed for changes made to |
There was a problem hiding this comment.
Is this covered by the RST warnings? Is there a style guide entry here?
There was a problem hiding this comment.
how could it - this is me editing prose to make words that should be literal, so - until we get AI in the pipeline this is not something we can test for
more generally - the use of * for literals relates to historic advice which i changed long ago
we could perhaps check for *word* and spellcheck the word as literals should not be marked up this way - it would catch some - ill look at it when i get to the spellcheck stuff
There was a problem hiding this comment.
I guess an alternative would be to clarify it in https://github.com/envoyproxy/envoy/blob/main/api/STYLE.md, but as long as we don't detect this in tooling, it will be hard to catch.
Can we hook a validation to the comments parser somehow?
There was a problem hiding this comment.
Can we hook a validation to the comments parser somehow?
this is what we do now for single backticks
for * or bare literals its much harder to detect - there are genuine uses of * - ie for italics/emphasis - and there is nothing to grep for with bare literals
spellchecking could work and catch most issues but not all and with some false +ves etc
this is something i intend to work, but not imminently - some preparatory work has been done over in pytooling tho
wrt to the STYLE guide i can update/review if you think it needs it but would suggest we follow up with that
There was a problem hiding this comment.
also - mho is that the best style guide is what is there - the more we clean stuff up the more people are working from examples that exemplify what we want
There was a problem hiding this comment.
also - mho is that the best style guide is what is there - the more we clean stuff up the more people are working from examples that exemplify what we want
I also tend to follow other examples.
phlax
changed the title
Signed-off-by: Ryan Northey <ryan@synca.io>
|
one thing im thinking - we could do with a "literals" policy (maybe that should be my rule of thumb is "would this be localized" - but that doesnt always help there are some grey areas, like HTTP or tldr - i think we just need to agree some rules/priorites regarding literals and code blocks and put those in the style guide - but lets follow up with that |
htuch
left a comment
htuch
left a comment
There was a problem hiding this comment.
Thanks for the cleanup. I do think it would be ideal to add at least a style guide entry in a followup, since this is the kind of thing that will regress. Examples are powerful, but some guidance is even better :P
Signed-off-by: Ryan Northey <ryan@synca.io> Signed-off-by: silverstar195 <seanmaloney@google.com> # Conflicts: # api/envoy/config/route/v3/route_components.proto
3 participants
Signed-off-by: Ryan Northey ryan@synca.io
Commit Message:
Additional Description:
Risk Level:
Testing:
Docs Changes:
Release Notes:
Platform Specific Features:
[Optional Runtime guard:]
[Optional Fixes #Issue]
[Optional Fixes commit #PR or SHA]
[Optional Deprecated:]
[Optional API Considerations:]