What does django.contrib.admindocs add to the Django admin, and what must you configure to enable it?

## What it is `django.contrib.admindocs` is a contrib app that turns your project's own code into browsable documentation inside the admin. It "pulls documentation from the docstrings of models, views, template tags, and template filters for any app in `INSTALLED_APPS`" and serves it under the admin's look and login. ## What it documents - **Models** — every field with its type and `help_text`, relations as links, and methods and properties with their docstrings. - **Views** — each URL pattern with its view's docstring, name and the pattern itself. - **Template tags and filters** — built-in and custom, with their docstrings. - **Templates** — looked up by path, showing which directories contain them. - **Bookmarklets** — browser shortcuts that jump from a page to the documentation of the view that rendered it. Docstrings can link to each other with reStructuredText roles: | Role | Links to | |---|---| | `:model:\`app_label.ModelName\`` | a model page | | `:view:\`app_label.view_name\`` | a view page | | `:tag:\`tagname\`` | a template tag | | `:filter:\`filtername\`` | a template filter | | `:template:\`path/to/template.html\`` | a template | Django 5.2 added custom link text in the form `:role:\`link text <link>\``. ## Enabling it 1. Add `"django.contrib.admindocs"` to `INSTALLED_APPS`. 2. Add `path("admin/doc/", include("django.contrib.admindocs.urls"))` to the root URLconf, **before** the `"admin/"` entry. The admin's own URL patterns end with a catch-all, so placed after it, `/admin/doc/` would be handled by the admin and never reach admindocs. 3. Install the **`docutils`** package — the pages render reStructuredText with it, and without it the views show an error page explaining that docutils is missing. Django 6.x, which needs Python 3.12, lists docutils 0.22 as the first compatible version. 4. Optionally add `django.contrib.admindocs.middleware.XViewMiddleware` for the bookmarklets; it adds an `X-View` header to `HEAD` requests from internal IPs or active staff. When the URL name `django-admindocs-docroot` can be reversed, the admin's header shows a **Documentation** link automatically. ## Who can see it - Every admindocs view is decorated with `staff_member_required`, so only active staff users get in. - Since **Django 5.2**, model pages are restricted to users with the view or change permission on that model. - It still reveals the project's structure — model fields, view names, URL patterns — to any staff user, so treat it as internal documentation, not something to expose to semi-trusted staff on a second admin site without thought. ## Where it earns its keep 1. Teams where non-developers maintain templates and need the list of available tags, filters and context. 2. Large projects where a browsable model reference helps support staff. 3. Projects that already write good docstrings; admindocs adds nothing to empty ones. It is rarely a deciding factor in an interview, but it shows familiarity with the contrib apps and with URL-ordering around the admin's catch-all. ## Writing docstrings that render well admindocs is only as good as the text it reads: - Give each model a class docstring that says what one row represents and how it relates to others, using `:model:` links. - Fill `help_text` on fields; admindocs shows it next to each field, and the admin forms show it too. - Document custom template tags and filters with their arguments and an example, since template authors are the main readers. - Give views a docstring naming the context variables and template they use, following the documented convention of **Context** and **Template:** sections. ## Checking it works 1. Visit the admin as a staff user and follow the **Documentation** link in the header. 2. Open a model page and confirm fields, relations and methods appear. 3. Log in as staff without view or change permission on that model and confirm its model page answers 403, as it does on Django 5.2 and later. 4. Uninstall `docutils` in a scratch environment to see the error page, so the failure mode is recognisable if a deployment misses the dependency.