Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Integrate Redoc REST API to mkdocs #47

Merged
merged 1 commit into from
Jun 10, 2024

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
3 checks passed
@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.

None yet

2 participants