docs: Add extension categories to extension docs#14721
docs: Add extension categories to extension docs#14721htuch merged 115 commits intoenvoyproxy:mainfrom
Conversation
Signed-off-by: Ryan Northey <ryan@synca.io>
|
CC @envoyproxy/api-shepherds: Your approval is needed for changes made to |
htuch
left a comment
There was a problem hiding this comment.
Nice, this looks like the right direction.
Signed-off-by: Ryan Northey <ryan@synca.io>
Signed-off-by: Ryan Northey <ryan@synca.io>
Signed-off-by: Ryan Northey <ryan@synca.io>
Signed-off-by: Ryan Northey <ryan@synca.io>
tools/protodoc/protodoc.py
Outdated
| for _k, _v in EXTENSION_DB.items(): | ||
| for _cat in _v['categories']: | ||
| EXTENSION_CATEGORIES.setdefault(_cat, []) | ||
| EXTENSION_CATEGORIES[_cat].append(_k) |
There was a problem hiding this comment.
@htuch i removed the script and shifted the code here
this simplifies/reduces the code and also parses the extension db only once (within this script), which should improve the efficiency of protodoc (if only by a tiny fraction im realising)
i have used setdefault as defaultdict adds some complexity and would prevent KeyErrors from being raised below
Signed-off-by: Ryan Northey <ryan@synca.io>
Signed-off-by: Ryan Northey <ryan@synca.io>
|
@htuch nits addressed (hopefully) |
|
/retest |
|
Retrying Azure Pipelines: |
| except KeyError as e: | ||
| raise ProtodocError(f"\n\nUnable to find extension category: {extension_category}\n\n") | ||
| anchor = FormatAnchor('extension_category_' + extension_category) | ||
| extensions = FormatExtensionList(sorted(extensions)) |
There was a problem hiding this comment.
move sorted into the extension list func
|
@phlax this is absolutely amazing. Well done. For future work, I'm wondering if we should do the following:
We should track these improvements in other issues? WDYT? |
i think it sounds like a good idea - altho from where i am working right now, im not entirely clear if we are talking about documenting end use (ie so, there are a couple of existing tickets in relation to this. i opened this one: mostly born from frustration of finding configuration examples using the older for the first part of the problem - upgrading - i guess its a lessening issue as time passes - perhaps we should just close it and focus forward the second part of it is where to get accurate info on extensions etc, which i think is the existing ticket that you had opened previously: i think that one has a partial fix with this PR - lets use it to track further improvements on the extension <> category docs |
Signed-off-by: Ryan Northey ryan@synca.io
Commit Message: docs: Add extension categories to extension docs
Additional Description:
Add information about known extension categories (types) to extension documentation
Risk Level:
Testing:
Docs Changes:
Release Notes:
Platform Specific Features:
[Optional Runtime guard:]
[Optional Fixes #Issue]
[Optional Deprecated:]