Project

Profile

Help

Task #2866

Generate auto-docs for the REST API and document it

Added by daviddavis almost 3 years ago. Updated 6 months ago.

Status:
CLOSED - CURRENTRELEASE
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 over 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 over 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 over 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 almost 3 years ago

  • Project changed from RPM Support to Pulp

#2 Updated by bmbouter almost 3 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 almost 3 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 almost 3 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 almost 3 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 almost 3 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 almost 3 years ago

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

#8 Updated by dkliban@redhat.com almost 3 years ago

dkliban will groom

#9 Updated by dkliban@redhat.com almost 3 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

#10 Updated by dkliban@redhat.com almost 3 years ago

  • Groomed changed from No to Yes

#11 Updated by mhrivnak almost 3 years ago

  • Priority changed from Normal to Low

#12 Updated by mhrivnak almost 3 years ago

  • Sprint/Milestone set to 42

#13 Updated by ttereshc almost 3 years ago

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

#14 Updated by mhrivnak almost 3 years ago

  • Priority changed from Low to High

#15 Updated by mhrivnak almost 3 years ago

  • Sprint/Milestone changed from 42 to 43

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

  • Sprint/Milestone changed from 43 to 44

#17 Updated by bizhang over 2 years ago

  • Assignee changed from ttereshc to bizhang

#18 Updated by mhrivnak over 2 years ago

  • Sprint/Milestone changed from 44 to 45

#19 Updated by bizhang over 2 years ago

  • Status changed from ASSIGNED to MODIFIED

#20 Updated by bizhang over 2 years ago

  • Status changed from MODIFIED to POST

whoops wrong state. Should be POST not MODIFIED

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

  • Sprint/Milestone changed from 45 to 46

#22 Updated by mhrivnak over 2 years ago

  • Sprint/Milestone changed from 46 to 47

#23 Updated by werwty over 2 years ago

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

#24 Updated by bmbouter over 2 years ago

  • Tags deleted (Pulp 3 Plugin Writer Alpha)

Cleaning up Redmine tags

#25 Updated by bmbouter about 2 years ago

  • Sprint set to Sprint 28

#26 Updated by bmbouter about 2 years ago

  • Sprint/Milestone deleted (47)

#27 Updated by daviddavis about 1 year ago

  • Sprint/Milestone set to 3.0.0

#28 Updated by bmbouter about 1 year ago

  • Tags deleted (Pulp 3)

#29 Updated by bmbouter 6 months ago

  • Status changed from MODIFIED to CLOSED - CURRENTRELEASE

Please register to edit this issue

Also available in: Atom PDF