Project

Profile

Help

Issue #3283

Descriptions for actions are based on docstring

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

Status:
CLOSED - CURRENTRELEASE
Priority:
Normal
Assignee:
Category:
-
Sprint/Milestone:
Start date:
Due date:
Estimated time:
Severity:
2. Medium
Version:
Platform Release:
OS:
Triaged:
No
Groomed:
No
Sprint Candidate:
No
Tags:
Sprint:
Quarter:

Description

Looks like drf maps docstring for viewset actions to a description field in the api schema. For example, our artifacts delete action looks like this in the api schema:

                "delete": {
                    "_type": "link",
                    "action": "delete",
                    "description": "Remove :class:`~pulpcore.app.models.Artifact` only if it is not associated with any\n`~pulpcore.app.models.Content`\n\nArgs:\n    request (:class:`rest_framework.request.Request`): request containing JSON payload\n        with information about the artifact being deleted.\n    pk (:class:`uuid.UUID`): Unique id of the artifact being deleted.\n\nReturns:\n    :class:`rest_framework.response.Response` with a 204 status code in case of\n        successful deletion, 409 status code if deletion is not allowed.",
...
}

This is from the docstring on the action here:

https://github.com/pulp/pulp/blob/3.0-dev/pulpcore/pulpcore/app/viewsets/content.py#L86-L98

This is probably not very friendly for API users. Not sure what the solution here is.

Other endpoints with this problem include content create, status, etc.


Related issues

Blocks Pulp - Story #3218: As an authenticated user, I can list repository version content, added content, removed contentCLOSED - CURRENTRELEASE

<a title="Actions" class="icon-only icon-actions js-contextmenu" href="#">Actions</a>

History

#1 Updated by daviddavis almost 3 years ago

  • Subject changed from Documentation for actions are hard to parse to Descriptions for actions are hard to parse and expose internal implementation

#2 Updated by daviddavis almost 3 years ago

  • Description updated (diff)

#3 Updated by bmbouter almost 3 years ago

We have a similar issue on errors that are recorded on Tasks. They are a single string with a bunch of '\n' characters in it. It looks bad visually. I think it's ok though because it's for machines, and when they render it for humans the '\n' will become newlines and it will look nice.

If I've missed the essence of this issue disregard this comment. :)

#4 Updated by daviddavis almost 3 years ago

bmbouter, the '\n' characters are only part of the problem. The other problem is that the description contains function arguments/return values/etc (request, response, etc) that only make sense if you look at the function. In our api schema, they don't make sense at all to our users.

#5 Updated by daviddavis almost 3 years ago

  • Subject changed from Descriptions for actions are hard to parse and expose internal implementation to Descriptions for actions are based on docstring

#6 Updated by daviddavis almost 3 years ago

bizhang mentioned that it's possible to maybe use a named section in our docstring to override these descriptions. See:

http://www.django-rest-framework.org/api-guide/schemas/#schemas-as-documentation

If that doesn't work, we could also use some custom schema generation.

#7 Updated by daviddavis almost 3 years ago

  • Blocks Story #3218: As an authenticated user, I can list repository version content, added content, removed content added

#8 Updated by daviddavis almost 3 years ago

I tried using alternative ways to document the viewset actions per comment #6 but they don't work.

Looking over the docstring we have in our viewsets, they really don't seem to add a lot of value. They seem to mostly document the internals of DRF. I'm tempted to remove them.

#9 Updated by daviddavis almost 3 years ago

  • Status changed from NEW to POST
  • Assignee set to daviddavis

#10 Updated by daviddavis almost 3 years ago

  • Status changed from POST to MODIFIED

#11 Updated by dkliban@redhat.com over 2 years ago

  • Sprint/Milestone set to 3.0.0

#12 Updated by bmbouter over 1 year ago

  • Tags deleted (Pulp 3, Pulp 3 MVP)

#13 Updated by bmbouter 12 months ago

  • Status changed from MODIFIED to CLOSED - CURRENTRELEASE

Please register to edit this issue

Also available in: Atom PDF