Skip to content

Conversation

@pedro-psb
Copy link
Member

@pedro-psb pedro-psb commented Jun 7, 2024

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

image

Changelog

image

- Inject Redoc html tags into final html on "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
@pedro-psb pedro-psb merged commit aeaac5a into pulp:main Jun 10, 2024
@pedro-psb pedro-psb deleted the add-simple-rest-api-redoc branch June 10, 2024 12:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants