How to make a django admin docs

Django is a great framework for web development in python. And the more I work with it the more I like it. One of the think I love with it is the fact that it provide a highly configurable admin interface. In few lines of code you can setup an admin interface for you web application. Today we will talk about one of the aspects of the Django admin: the django admin docs.

Working on a project with a team, need a lot of communication between members to keep everybody a the same level of information. Django already have turn key solution to display on web based the a documentation of all your views, filters, templates, etc using docstring.

Docstring comments

Docstring is a convenient way to provide documentation in python: for classes, functions, modules, etc.
It must be insert as the first statement of the object. It should describe the object:

A docstring must be enclosed by three “. It can be on multi lines and you can can even add html code in it.

class HClass(object):
    """
    Docstring for the class 
    """

    def funct(param1, param2):
        """Docstring for the function"""
        pass

Django will parse the docstring in your code and generate a beautiful html documentation.

Django admin docs

Admin docs are built by pulling docstring from models, views, template tags, and template filters for any applications in INSTALLED_APPS. You can use markdown in your docstring to customize the display in html: Django will understand it. Like the admin interface, add the admin doc is very simple.

Installation

It already present in django you just have to activate it. To do that just follow the few steps below:

Tadaa!!! your admin docs is activated and it will be available on the admin page (top and right of the page)

Populating of your django admin doc

As already told on above, admin docs is generated from docstring extracted in source code. So once it activated, just make docstring in your views, models, filters, etc. and you will have it automatically in your docs.

One interested thing here is that you can link elements of your doc together by using references. For that, Django already provide helpers that you can just add them in your docstring.

Django Component	doctring text
Models	:model:`app_label.ModelName`
Views	:view:`app_label.view_name`
Template tags	:tag:`tagname`
Template filters	:filter:`filtername`
Templates	:template:`path/to/template.html`

Example:

from django.shortcuts import render

from myapp.models import MyModel

def my_view(request, slug):
    """
    Display an individual :model:`myapp.MyModel`.

    **Context**

    ``mymodel``
        An instance of :model:`myapp.MyModel`.

    **Template**

    :template:`myapp/my_template.html`
    """
    context = {'mymodel': MyModel.objects.get(slug=slug)}
    return render(request, 'myapp/my_template.html', context)

Thanks for reading.

Sources: