Task #2866
closed
Generate auto-docs for the REST API and document it
100%
Description
Before we get too far into developing Pulp 3, we should figure out how to generate the REST API documentation. This would help us to confirm that it'll suffice for our users and make sure it actually works.
Consider also adding a Travis task to make sure new PRs/changes don't break the auto-generated doc generation too.
Updated by bmbouter over 7 years ago
- Sprint Candidate changed from No to Yes
If the docs get built with Sphinx then they automatically get built with each PR already as part of #2352. Sphinx is what generates all of our docs so my main question is what autodoc API capabilities does DRF provide to integrate w/ Sphinx.
Which section of the revised layout should hold the docs?
Updated by amacdona@redhat.com over 7 years ago
bmbouter wrote:
Which section of the revised layout should hold the docs?
We've got "API Reference" as a top level section in the planning pad.
Updated by amacdona@redhat.com over 7 years ago
- Subject changed from Figure out how to generate documentation for the REST API and document it to Generate documentation for the REST API and document it
Updated by amacdona@redhat.com over 7 years ago
- Subject changed from Generate documentation for the REST API and document it to Generate auto-docs the REST API and document it
Updated by amacdona@redhat.com over 7 years ago
- Subject changed from Generate auto-docs the REST API and document it to Generate auto-docs for the REST API and document it
Updated by amacdona@redhat.com over 7 years ago
- Tags Pulp 3 Plugin Writer Alpha added
- Tags deleted (
Documentation)
Updated by dkliban@redhat.com over 7 years ago
We should use sphinx-swaggerdoc[0] to document our REST API. One of requirements is that Pulp exposes it's API schema using swagger. This can be achieved with a django-rest-swagger[1]. We should probably add it as a dependency to Pulp. Or we can use it just when deploying for doc building. The docs would then be generated like this:
The doc builder Jenkins job deploys Pulp. Then while the docs are being built, the REST API docs pages are generated based on the swagger schema exposed by Pulp.
[0] https://github.com/unaguil/sphinx-swaggerdoc
[1] https://github.com/marcgibbons/django-rest-swagger
Updated by ttereshc over 7 years ago
- Status changed from NEW to ASSIGNED
- Assignee set to ttereshc
Updated by jortel@redhat.com over 7 years ago
- Sprint/Milestone changed from 43 to 44
Updated by bizhang about 7 years ago
- Status changed from ASSIGNED to MODIFIED
Updated by bizhang about 7 years ago
- Status changed from MODIFIED to POST
whoops wrong state. Should be POST not MODIFIED
Updated by jortel@redhat.com about 7 years ago
- Sprint/Milestone changed from 45 to 46
Added by werwty about 7 years ago
Added by werwty about 7 years ago
Revision fe809b4c | View on GitHub
Add drf-openapi docs
Imports drf-openapi dependecy to generate openapi compliant schema.
The docs can be accessed at localhost/api/v3/docs/
Build sphinx REST API docs, document how API docs are generated.
Added by werwty about 7 years ago
Revision d5430c70 | View on GitHub
Separate pulp3-docs builder jobs from pulp2-docs builder jobs.
Pulp3 has to be installed and running before rest api docs can be built. We should install pulp3 from ansible roles and start pulp3 server in background with django runserver, before building the docs.
Updated by werwty about 7 years ago
- Status changed from POST to MODIFIED
- % Done changed from 0 to 100
Applied in changeset packaging:d5430c700c418aad64b8a3f103c70a3c30f04ccd.
Updated by bmbouter about 7 years ago
- Tags deleted (
Pulp 3 Plugin Writer Alpha)
Cleaning up Redmine tags
Updated by bmbouter about 5 years ago
- Status changed from MODIFIED to CLOSED - CURRENTRELEASE
.
Add drf-openapi docs
Imports drf-openapi dependecy to generate openapi compliant schema.
The docs can be accessed at localhost/api/v3/docs/
Build sphinx REST API docs, document how API docs are generated.
re #2866 https://pulp.plan.io/issues/2866