Feature/action docs sections by OmegaDroid · Pull Request #6060 · encode/django-rest-framework (original) (raw)

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service andprivacy statement. We’ll occasionally send you account related emails.

Already on GitHub?Sign in to your account

Conversation11 Commits5 Checks0 Files changed

Conversation

This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.Learn more about bidirectional Unicode characters

[ Show hidden characters]({{ revealButtonHref }})

Description

I require the ability to split action data documentation into sections (similar to list: .. create: ... from the viewsets docstring).

I've altered the code so that the method docstring is handled in a similar way to the viewsets description which allows for the documentation sections on actions using get:, post: etc.

Cheers

This would be a good complement to the work done in #5605. I'm curious if this would work as expected with the method mapping introduced in the PR. e.g., something like:

class SomeViewSet(viewsets.ModelViewSet):

@action(detail=False, methods=['get', 'post'])
def some_action(self, request, *args, **kwargs):
    """
    get:
    A description of the get method on the custom action.

    post:
    A description of the post method on the custom action.
    """

@some_action.mapping.put
def put_some_action():
    """
    A description of the put method on the custom action.
    """

I'm adding this to the 3.9 milestone to ensure it's considered.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

#5605 is in, so we should consider that.

In general I want to avoid adding complexity to the docstring parsing, since that way lies insanity. But this particular change is small, so it may be worth it.

Hi @OmegaDroid. Would you be willing to write a test for extra actions, as laid out above?

@rpkilby yeah i'll take a look, do you mean writing tests for adding docs from action.mapping functionality?

Yes - that would be great if you have the time. Ideally, the docs would include sections for all three HTTP methods.

This is OK I think, except totally undocumented. It needs an addition to the Documenting your views section of the docs there.

Inclined to hold-off until we see how #6119 comes out.

I'm going to de-milestone. @OmegaDroid If you add the docs I'm happy to merge it.

Codecov Report

Merging #6060 into master will decrease coverage by 0.35%.
The diff coverage is 71.42%.

@@ Coverage Diff @@ ## master #6060 +/- ##

• Coverage 96.18% 95.82% -0.36%

  Files 128 129 +1
  Lines 17630 17877 +247
  Branches 1458 1479 +21

• Hits 16957 17131 +174

• Misses 465 540 +75

• Partials 208 206 -2

Hi @carltongibson, I've added some docs for the custom action documentation. Let me know if there's anything else.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK. Thanks for the update @OmegaDroid. Super effort.

pchiquet pushed a commit to pchiquet/django-rest-framework that referenced this pull request

Nov 17, 2020

• added ability to add sections to custom action documentation

• added tests to cover docs sections in custom actions

• added method specific docs test for action mapping

• added docs for custom action documentation