Project

Profile

Help

Task #3958

Viewset docstring written from developer perspective

Added by daviddavis about 1 year ago. Updated 6 months ago.

Status:
CLOSED - CURRENTRELEASE
Priority:
Normal
Assignee:
-
Category:
-
Sprint/Milestone:
Start date:
Due date:
% Done:

0%

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

Description

In numerous places throughout our codebase (and plugin codebase), we've written View and Viewset docstrings to contain developer information (e.g. [0]). We refer to classes and such in the docstring.

The problem is that DRF uses this docstring to fill in descriptions in the API. See:

http://www.django-rest-framework.org/topics/documenting-your-api/#documenting-your-views

Not really sure what the solution is but reading the API schema is confusing for users.

[0] https://gist.github.com/daviddavis/c44692ba1675be75c4e0dfed15c2fca0#file-gistfile1-txt-L3 comes from https://git.io/fAcub

History

#1 Updated by daviddavis about 1 year ago

  • Tracker changed from Issue to Task
  • % Done set to 0

#2 Updated by daviddavis about 1 year ago

Recent change in: https://github.com/axnsan12/drf-yasg/issues/205.

We need to ensure the first line is relevant to users and then add the developer docs on the following lines of docstring.

#3 Updated by vdusek about 1 year ago

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

#4 Updated by vdusek 11 months ago

  • Status changed from ASSIGNED to NEW
  • Assignee deleted (vdusek)

#5 Updated by amacdona@redhat.com 11 months ago

  • Tags Documentation added

#6 Updated by amacdona@redhat.com 6 months ago

  • Status changed from NEW to CLOSED - CURRENTRELEASE

This is still a problem, but it is spread out over many objects. I think the best thing to do is to close this and open issues for any autogenerated docs that don't make sense to the user. I am closing as a duplicate because it will be covered by the more specific issues.

Per object, the solution I've merged to pulp_python is to flag certain docstrings as user-facing docs. We can also add style using simple html tags. https://github.com/pulp/pulp_python/blob/4939808effd8a824452cc1798e6aac449be53cc4/pulp_python/app/viewsets.py#L143-L146

#7 Updated by bmbouter 6 months ago

  • Tags deleted (Pulp 3)

Please register to edit this issue

Also available in: Atom PDF