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:

• What is the purpose of the object
• What does it return
• Specified if it raise some exception

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

python153 B
Copy

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:

• Add django.contrib.admindocs to your INSTALLED_APPS.
• Add url(r'^admin/doc/', include('django.contrib.admindocs.urls')) to your urlpatterns. Make sure it’s included before the r'^admin/' entry, so that requests to /admin/doc/ don’t get handled by the latter entry.
• Install the docutils Python module (http://docutils.sf.net/).

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.

Composant Django	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:

425 B
Copy

Thanks for reading.

Sources:

• https://docs.djangoproject.com/en/1.11/ref/contrib/admin/admindocs/