Use more Redoc render features (REST API)
Nobody has claimed this yet.
Assessment
- Difficulty
- 5/5
- Estimated time
- Over a week
- Newbie friendliness
- 25/100
- Issue type
- Feature
- Clarity
- Needs clarification
- Activity status
- Stale
- Tech stack
- openapi
- Domain
- api, documentation
Research direction
Start with the linked Redoc demo/openapi.yaml and run the provided podman redoc container command to inspect the referenced render features. Investigate whether the required changes belong in pulp-docs, DRF, or spectacular. Done would require an agreed scope and API documentation demonstrating selected section groups, text sections, or deprecated fields and endpoints.
Written by the indexing model from the issue text.
Description
Problem
The Redoc API render engine has some under-used features (attached below).
Approach
Actually, the changes that can make it better may not belong to pulp-docs itself, but I'll put here to expose the big picture.
We should investigate how we can change DRF/spectacular/??? to make use of those.
To test the API website that originated the snapshots, run the code below.
Notice the relevant schema reference is this.
podman pull redocly/redoc # from docker registry
podman run --rm \
-p 8080:80 \
-e SPEC_URL=https://raw.githubusercontent.com/Redocly/redoc/refs/heads/main/demo/openapi.yaml \
redocly/redoc
Snapshots
Section groups
We can use sections like "Content Management", "Auth", "Admin", etc.
An opportunity to logically group pulp entities from the user perspective.
Text Sections
We can write text section that appear in the navigation.
This can be used for presenting useful links and info.
Some ideas:
Listing links to supported API pages (and provide the Redoc for those, of course):
## Supported versions
- [3.39](site:pulpcore/restapi/3.39/)
- [3.22](site:pulpcore/restapi/3.22/)
- [3.21](site:pulpcore/restapi/3.21/)
Shortcut links to other plugin API docs:
## Other plugins
[pulp_file](...) - [pulp_python](...) - [pulp_rpm](...) - etc
Deprecated field and endpoint
Just looks better and more obvious that you shouldn't use it.
- Dominant language
- HTML
- Stars
- 2
- Forks
- 17
- Avg merge
- 7d 18h
- Merged PRs (30d)
- 3
Getting set up
- Ships a Dockerfile or Docker Compose file
- No pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from pulp/pulp-docs
-
epic
Difficulty 5/5 Over a week Newbie friendliness 25/100
-
bug
Difficulty 3/5 1-2 days Newbie friendliness 48/100
-
documentation
Difficulty 3/5 1-2 days Newbie friendliness 45/100
-
Add issue templatesOpenenhancement
Difficulty 2/5 1-3 hours Newbie friendliness 55/100
-
enhancement
Difficulty 3/5 1-2 days Newbie friendliness 45/100
Similar issues
-
tool-calling
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
vllm-project/vllm#59838 ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
raullenchai/Rapid-MLX#4037 ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 85/100
diegosouzapw/OmniRoute#15401 ·
Maintainers usually reply within 2 days
-
Difficulty 2/5 1-3 hours Newbie friendliness 84/100
paperclipai/paperclip#14982 ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
Maintainers usually reply within 1 day