[WIP] docs: Fix broken :refs: and other api issues

[phlax]

Signed-off-by: Ryan Northey ryan@synca.io

Commit Message: docs: Fix broken :refs: and other api issues
Additional Description:

adds a grep check for:

• broken refs
• incorrectly rendered annotations (currently comments, and not-implemented-hide)

...in the docs build and fixes the related issues

this can be updated to also include rstcheck but will require a bit more work (pr here for progress #15786 )

Risk Level:
Testing:
Docs Changes:
Release Notes:
Platform Specific Features:
[Optional Runtime guard:]
[Optional Fixes #Issue] Fix #15710
[Optional Deprecated:]
[Optional API Considerations:]

[repokitteh-read-only]

CC @envoyproxy/api-shepherds: Your approval is needed for changes made to api/envoy/.
API shepherd assignee is @lizan
CC @envoyproxy/api-watchers: FYI only for changes made to api/envoy/.

🐱

Caused by: #15766 was opened by phlax.

see: more, trace.

[phlax]

add function signature

[htuch]

You have another WiP PR here; a bit confused..

[phlax]

so the point was to move it there once that PR landed

i wanted to land this because it fixes actual problems, and then add a better solution in the follow up #15786

[htuch]

Can you let me know when the Python is ready for final review?

[htuch]

/wait

[htuch]

Probably best to factor out the decode stuff for clarity.

[htuch]

Is the plan to expand this beyond just grep checking? If it's a grep wrapper, then a shell script is fine.

[phlax]

my plan is to rewrite it with the proper rstcheck (ie #15786 ) and using class like in #15802 so its kinda temporary to do it this way - but it fixes the immediate issue and introduces the generated rst checking

[phlax]

setting this to wip until other work has been done around tests/checks

[phlax]

closing this in favour of #15786 - the fixes here are already landed