Skip to main content

Automated Documentation with admindocs

The admindocs application provides a web interface for browsing technical documentation generated directly from your project's models, views, template tags, and filters. It uses reStructuredText (reST) to parse docstrings and provides specialized roles for cross-referencing components.

Enabling admindocs in Your Project​

To use admindocs, you must add it to your INSTALLED_APPS and include its URL patterns in your root URLconf.

# settings.py
INSTALLED_APPS = [
    ...
    "django.contrib.admin",
    "django.contrib.admindocs",  # Required for documentation generation
    ...
]

# urls.py
from django.contrib import admin
from django.urls import include, path

urlpatterns = [
    path('admin/doc/', include('django.contrib.admindocs.urls')),
    path('admin/', admin.site.urls),
]

Identifying Views with XViewMiddleware​

The XViewMiddleware allows you to identify which view function is handling a specific URL by sending a HEAD request. This is particularly useful for debugging or when using the admindocs interface to jump from a page to its documentation.

Add XViewMiddleware to your MIDDLEWARE setting:

# settings.py
MIDDLEWARE = [
    "django.contrib.sessions.middleware.SessionMiddleware",
    "django.contrib.auth.middleware.AuthenticationMiddleware",
    "django.contrib.admindocs.middleware.XViewMiddleware",  # Add this
    ...
]

When enabled, a HEAD request from a staff member or an IP in INTERNAL_IPS will return an X-View header:

# django/contrib/admindocs/middleware.py

class XViewMiddleware(MiddlewareMixin):
    def process_view(self, request, view_func, view_args, view_kwargs):
        # Requires AuthenticationMiddleware to be installed
        if not hasattr(request, "user"):
            raise ImproperlyConfigured(...)
            
        # Only triggers on HEAD requests for staff or internal IPs
        if request.method == "HEAD" and (
            request.META.get("REMOTE_ADDR") in settings.INTERNAL_IPS
            or (request.user.is_active and request.user.is_staff)
        ):
            response = HttpResponse()
            response.headers["X-View"] = get_view_name(view_func)
            return response

Writing Documentation with reST Roles​

admindocs uses docutils to parse your docstrings as reStructuredText. You can use specialized roles defined in django/contrib/admindocs/utils.py to link between different parts of the documentation.

Available roles include:

  • :model:: Link to a model's documentation.
  • :view:: Link to a view's documentation.
  • :template:: Link to a template's documentation.
  • :tag:: Link to a template tag's documentation.
  • :filter:: Link to a template filter's documentation.

Example docstring in a view:

def my_view(request):
    """
    Display a list of :model:`myapp.MyModel`.
    
    This view uses the :template:`myapp/my_template.html` template.
    For more info, see the :view:`myapp.views.another_view`.
    """
    return render(request, 'myapp/my_template.html')

Access Control and Requirements​

The admindocs views inherit from BaseAdminDocsView, which enforces specific requirements for access and rendering.

Staff Permissions​

All documentation views are protected by the @staff_member_required decorator. Users must be logged in as staff to view any documentation.

# django/contrib/admindocs/views.py

class BaseAdminDocsView(TemplateView):
    @method_decorator(staff_member_required)
    def dispatch(self, request, *args, **kwargs):
        if not utils.docutils_is_available:
            # If docutils is not installed, show a warning template
            self.template_name = "admin_doc/missing_docutils.html"
            return self.render_to_response(admin.site.each_context(request))
        return super().dispatch(request, *args, **kwargs)

Model Documentation Permissions​

While the general documentation is available to all staff, model-specific documentation (via ModelDetailView) is restricted. A user can only see documentation for a model if they have the view or change permission for that specific model.

Troubleshooting: Missing docutils​

If you see the "docutils not installed" error page, you must install the docutils package in your environment:

pip install docutils

Without docutils, admindocs cannot parse reST and will display the admin_doc/missing_docutils.html template instead of the technical documentation.