Project

Profile

Help

Task #3958

closed

Viewset docstring written from developer perspective

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

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

0%

Estimated time:
Platform Release:
Groomed:
No
Sprint Candidate:
No
Tags:
Documentation
Sprint:
Quarter:

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

Actions #1

Updated by daviddavis over 5 years ago

  • Tracker changed from Issue to Task
  • % Done set to 0
Actions #2

Updated by daviddavis over 5 years 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.

Actions #3

Updated by vdusek over 5 years ago

  • Status changed from NEW to ASSIGNED
  • Assignee set to vdusek
Actions #4

Updated by vdusek over 5 years ago

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

Updated by amacdona@redhat.com over 5 years ago

  • Tags Documentation added
Actions #6

Updated by amacdona@redhat.com almost 5 years 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

Actions #7

Updated by bmbouter almost 5 years ago

  • Tags deleted (Pulp 3)

Also available in: Atom PDF