Integrate Redoc REST API to mkdocs - Githubissues

pulp / pulp-docs

Python Package to help aggregating Pulp's multirepo ecosystem into a unified doc.

https://pedro-psb.github.io/pulp-docs/

2 stars 4 forks source link

Integrate Redoc REST API to mkdocs #47

Closed pedro-psb closed 2 months ago

pedro-psb commented 2 months ago

The mkdocs plugins I've tried for openapi-schema display (example) don't support anchoring the endpoint links, which is something we do all the time.

Because of that, I've decided to bake a simple solution based on what we did with sphinx, with a small bonus of keeping mkdocs top header.

This does:

Download api.json from https://docs.pulpproject.org/{plugin}/api.json
Inject Redoc scripts into HTML api page. Uses the "on_post_page" mkdocs hook
Change navigation:
- Add "UserManual/{plugin}/restapi/"
- Move CHANGES.md nav to "UserManual/{plugin}/changes/"
Fix "Help#quick-links" table links

Known limitation:

No dark-mode theme support. But I'm pretty sure there is some Redoc dark theme out there which we can use.
Search doesnt work w/ endpoints, because its JS stuff. But I have a simple idea that may get around that.
For now getting api.json from https://docs.pulpproject.org/{plugin}/api.json works, but this should break soon.

Screenshots

REST API

Changelog