Project

Profile

Help

Task #2866

Generate auto-docs for the REST API and document it

Added by daviddavis over 2 years ago. Updated 6 months ago.

Status:
MODIFIED
Priority:
High
Assignee:
Category:
-
Sprint/Milestone:
Start date:
Due date:
% Done:

100%

Platform Release:
Blocks Release:
Backwards Incompatible:
No
Groomed:
Yes
Sprint Candidate:
Yes
Tags:
QA Contact:
Complexity:
Smash Test:
Verified:
No
Verification Required:
No
Sprint:
Sprint 28

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.


Checklist

Associated revisions

Revision fe809b4c View on GitHub
Added by werwty almost 2 years ago

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

Revision fe809b4c View on GitHub
Added by werwty almost 2 years ago

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

Revision fe809b4c View on GitHub
Added by werwty almost 2 years ago

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

Revision d5430c70 View on GitHub
Added by werwty almost 2 years ago

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.

closes #2866
https://pulp.plan.io/issues/2866

History

#1 Updated by daviddavis over 2 years ago

  • Project changed from RPM Support to Pulp

#2 Updated by bmbouter over 2 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?

#3 Updated by amacdona@redhat.com over 2 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.

http://pad-katello.rhcloud.com/p/pulp3_doc_structure

#4 Updated by amacdona@redhat.com over 2 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

#5 Updated by amacdona@redhat.com over 2 years ago

  • Subject changed from Generate documentation for the REST API and document it to Generate auto-docs the REST API and document it

#6 Updated by amacdona@redhat.com over 2 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

#7 Updated by amacdona@redhat.com over 2 years ago

  • Tags Pulp 3 Plugin Writer Alpha added
  • Tags deleted (Documentation)

#8 Updated by dkliban@redhat.com over 2 years ago

dkliban will groom

#9 Updated by dkliban@redhat.com about 2 years ago

We should use sphinx-swaggerdoc0 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-swagger1. 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

#10 Updated by dkliban@redhat.com about 2 years ago

  • Groomed changed from No to Yes

#11 Updated by mhrivnak about 2 years ago

  • Priority changed from Normal to Low

#12 Updated by mhrivnak about 2 years ago

  • Sprint/Milestone set to 42

#13 Updated by ttereshc about 2 years ago

  • Status changed from NEW to ASSIGNED
  • Assignee set to ttereshc

#14 Updated by mhrivnak about 2 years ago

  • Priority changed from Low to High

#15 Updated by mhrivnak about 2 years ago

  • Sprint/Milestone changed from 42 to 43

#16 Updated by jortel@redhat.com about 2 years ago

  • Sprint/Milestone changed from 43 to 44

#17 Updated by bizhang about 2 years ago

  • Assignee changed from ttereshc to bizhang

#18 Updated by mhrivnak about 2 years ago

  • Sprint/Milestone changed from 44 to 45

#19 Updated by bizhang about 2 years ago

  • Status changed from ASSIGNED to MODIFIED

#20 Updated by bizhang almost 2 years ago

  • Status changed from MODIFIED to POST

whoops wrong state. Should be POST not MODIFIED

#21 Updated by jortel@redhat.com almost 2 years ago

  • Sprint/Milestone changed from 45 to 46

#22 Updated by mhrivnak almost 2 years ago

  • Sprint/Milestone changed from 46 to 47

#23 Updated by werwty almost 2 years ago

  • Status changed from POST to MODIFIED
  • % Done changed from 0 to 100

#24 Updated by bmbouter almost 2 years ago

  • Tags deleted (Pulp 3 Plugin Writer Alpha)

Cleaning up Redmine tags

#25 Updated by bmbouter over 1 year ago

  • Sprint set to Sprint 28

#26 Updated by bmbouter over 1 year ago

  • Sprint/Milestone deleted (47)

#27 Updated by daviddavis 6 months ago

  • Sprint/Milestone set to 3.0

#28 Updated by bmbouter 6 months ago

  • Tags deleted (Pulp 3)

Please register to edit this issue

Also available in: Atom PDF