Skip to content
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 and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Feature/action docs sections #6060

Merged
merged 5 commits into from
Oct 10, 2018

Conversation

OmegaDroid
Copy link
Contributor

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

@rpkilby
Copy link
Member

rpkilby commented Jun 26, 2018

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.
        """

@rpkilby
Copy link
Member

rpkilby commented Jun 26, 2018

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

@rpkilby rpkilby added this to the 3.9 Release milestone Jun 26, 2018
Copy link
Collaborator

@carltongibson carltongibson left a comment

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.

@rpkilby
Copy link
Member

rpkilby commented Sep 11, 2018

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

@OmegaDroid
Copy link
Contributor Author

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

@rpkilby
Copy link
Member

rpkilby commented Sep 11, 2018

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

@carltongibson
Copy link
Collaborator

carltongibson commented Oct 2, 2018

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.

@carltongibson carltongibson removed this from the 3.9 Release milestone Oct 2, 2018
@encode encode deleted a comment from codecov-io Oct 3, 2018
@codecov-io
Copy link

codecov-io commented Oct 8, 2018

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

@OmegaDroid
Copy link
Contributor Author

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

@rpkilby
Copy link
Member

rpkilby commented Oct 9, 2018

Thanks @OmegaDroid for putting the work in on this.

Copy link
Collaborator

@carltongibson carltongibson left a comment

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.

@carltongibson carltongibson added this to the 3.9 Release milestone Oct 10, 2018
@carltongibson carltongibson merged commit 5feb835 into encode:master Oct 10, 2018
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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants