Task #3958
closed
Viewset docstring written from developer perspective
0%
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
Updated by daviddavis about 6 years ago
- Tracker changed from Issue to Task
- % Done set to 0
Updated by daviddavis about 6 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.
Updated by vdusek about 6 years ago
- Status changed from NEW to ASSIGNED
- Assignee set to vdusek
Updated by vdusek about 6 years ago
- Status changed from ASSIGNED to NEW
- Assignee deleted (
vdusek)
Updated by amacdona@redhat.com over 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
.