How to dinstinctly document possible REST actions in ViewSet docstring?

Question

The DRF docs mention this:

Note that when using viewsets the basic docstring is used for all generated views. To provide descriptions for each view, such as for the the list and retrieve views, use docstring sections as described in Schemas as documentation: Examples.

But the link is bad, and the similar link, https://www.django-rest-framework.org/api-guide/schemas/, doesn't mention these "sections."

How do I distinctly document my different possible REST actions within my single Viewset when it is composed like,

class ViewSet(mixins.ListModelMixin,                                            
              mixins.RetrieveModelMixin,                                        
              mixins.CreateModelMixin,                                          
              mixins.UpdateModelMixin,                                        
              ):       

Answer 1

I came here from Google after spending ages tracking this down. There is indeed a special formatting of the docstring to document individual methods for ViewSets.

The relevant example must have been removed from the documentation at some point but I was able to track this down in the source. It is handled by the function get_description in https://github.com/encode/django-rest-framework/blob/master/rest_framework/schemas/coreapi.py

The docstring format is based on the action names (if view.action is defined):

"""
General ViewSet description

list: List somethings

retrieve: Retrieve something

update: Update something

create: Create something

partial_update: Patch something

destroy: Delete something
"""

If view.action is not defined, it falls back to the method name: get, put, patch, delete.

Each new section begins with a lower case HTTP method name followed by colon.