The Django REST Framework is awesome, for a whole bunch of reasons, one of them being the browsable HTML version of your API that it automatically generates for you.

As a part of this, it extracts any docstrings that you might have defined for the relevant class (ViewSet or CBV) and adds an HTML version of this documentation to the browsable API, like this:

However, as described in the relevant documentation, it expects Markdown syntax by default. I like Markdown, but the rest of my Python docstrings are all in reStructuredText, which is the default documentation format for many Python projects.

In short, I would prefer to type my view docstrings in reStructuredText and not in the DRF-default markdown, because reStructuredText is what all of my other non-DRF code is using.

Fortunately, DRF has made this relatively easily configurable, if you’re not afraid to do some searching and digging (I couldn’t find a single complete worked-out example). Especially the code for transforming RST text into parsed HTML is not as straight-forward as one would have hoped. The DRF part of the deal is clearly described in its documentation.

Here’s how you can do this:

Define a new DRF view description function

Add the following function to your code somewhere. I added it to the views module in a Django app with reusable library code: 

<pre class="brush: python; title: ; notranslate" title="">

from django.utils.safestring import mark_safe from docutils import core from rest_framework.compat import smart_text from rest_framework.utils import formatting

def get_view_description(view_cls, html=False): “““Alternative view description function to be used as the DRF VIEW_DESCRIPTION_FUNCTION so that RestructuredText can be used instead of the DRF-default MarkDown.

Except for the RST parts, derived by cpbotha@vxlabs.com from the
DRF default get_view_description function.

"""

description = view_cls.__doc__ or ''
description = formatting.dedent(smart_text(description))
if html:
    # from https://wiki.python.org/moin/ReStructuredText -- we use the
    # third recipe to get just the HTML parts corresponding to the ReST
    # docstring:
    parts = core.publish_parts(source=description, writer_name='html')
    html = parts['body_pre_docinfo']+parts['fragment']
    # have to use mark_safe so our HTML will get explicitly marked as
    # safe and will be correctly rendered
    return mark_safe(html)

return description

Configure the view description function

In your settings, activate the new view description function: 

<pre class="brush: python; title: ; notranslate" title="">

REST_FRAMEWORK = { # other REST_FRAMEWORK config here… ‘VIEW_DESCRIPTION_FUNCTION’: ‘your_app.views.get_view_description’ }

Enjoy your reStructuredText

If you now reload any of your browsable API pages, you should see your reStructuredText nicely parsed.