Task #2866: Generate auto-docs for the REST API and document it - Pulp

Agile board
Agile charts

Agile boards

Pulp 2 QE Agile Board
Pulp 2 QE Agile Board - Priority View
Pulp 3 QE Agile Board
Pulp 3 RPM Tests Agile Board
Sprint 112 Agile Board

Custom queries

[All Projects] All Test Trackers
2.21.4 - Next Bugfix Release
2.21.4 MODIFIED
2.21.5
3.14.3
CI/CD
Easy Fix
FIPS open
Functional Tests
Galaxy NG
Groomed
Installer - Triage
Installer Items
Issues for Triage
Katello Integration
Next Docs Day
Operator issues
POST/ASSIGNED - no Sprint - Pulp2
POST/ASSIGNED - no Sprint - Pulp3
Prioritized Bugs
Pulp 3 Docs issues
Pulp2 issues available for next release
Pulpcore
SELinux related
Sprint 111
Sprint 112
Sprint Candidates (also groomed)
Un-Triaged Bugs
Verification Required

Actions

Send by e-mail Copy link

Task #2866

closed

Generate auto-docs for the REST API and document it

Added by daviddavis over 7 years ago. Updated almost 5 years ago.

Status:

CLOSED - CURRENTRELEASE

Priority:

High

Assignee:

bizhang

Category:

Sprint/Milestone:

3.0.0

Start date:

Due date:

% Done:

100%

Estimated time:

Platform Release:

Groomed:

Yes

Sprint Candidate:

Yes

Tags:

Sprint:

Sprint 28

Quarter:

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.

History
Notes
Property changes
Associated revisions

Actions

Copy link

Updated by daviddavis over 7 years ago

Project changed from RPM Support to Pulp

Actions

Copy link

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?

Actions

Copy link

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.

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

Actions

Copy link

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

Actions

Copy link

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

Actions

Copy link

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

Actions

Copy link

Updated by amacdona@redhat.com over 7 years ago

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

Actions

Copy link

Updated by dkliban@redhat.com over 7 years ago

dkliban will groom

Actions

Copy link

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

Actions

Copy link

#10

Updated by dkliban@redhat.com over 7 years ago

Groomed changed from No to Yes

Actions

Copy link

#11

Updated by mhrivnak over 7 years ago

Priority changed from Normal to Low

Actions

Copy link

#12

Updated by mhrivnak over 7 years ago

Sprint/Milestone set to 42

Actions

Copy link

#13

Updated by ttereshc over 7 years ago

Status changed from NEW to ASSIGNED
Assignee set to ttereshc

Actions

Copy link

#14

Updated by mhrivnak over 7 years ago

Priority changed from Low to High

Actions

Copy link

#15

Updated by mhrivnak over 7 years ago

Sprint/Milestone changed from 42 to 43

Actions

Copy link

#16

Updated by jortel@redhat.com about 7 years ago

Sprint/Milestone changed from 43 to 44

Actions

Copy link

#17

Updated by bizhang about 7 years ago

Assignee changed from ttereshc to bizhang

Actions

Copy link

#18

Updated by mhrivnak about 7 years ago

Sprint/Milestone changed from 44 to 45

Actions

Copy link

#19

Updated by bizhang about 7 years ago

Status changed from ASSIGNED to MODIFIED

PR: https://github.com/pulp/pulp/pull/3194

Actions

Copy link

#20

Updated by bizhang about 7 years ago

Status changed from MODIFIED to POST

whoops wrong state. Should be POST not MODIFIED

Actions

Copy link

#21

Updated by jortel@redhat.com about 7 years ago

Sprint/Milestone changed from 45 to 46

Actions

Copy link

#22

Updated by mhrivnak about 7 years ago

Sprint/Milestone changed from 46 to 47

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.

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

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.

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

Added by werwty almost 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.

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

Actions

Copy link

#23