Django admin/doc/views/ all blank or broken

I'm try开发者_JAVA百科ing to use Django's built-in admin docs feature to make writing templates easier. Supposedly if you go to /admin/docs/views you should get documentation for every view in your application. I see a list, but none of the links work:

-) Any view listed that's related to my application just goes to a blank page with nothing but the name of the view as a header.

-) The views related to admin all give me Django 404 errors when I click on them, except those that are related to the docs itself. The docs-related links also give me blank pages. (i.e. clicking /admin/doc/filters gives a blank page with nothing but "django.contrib.admindocs.views.template_filter_index" as a title, but clicking /admin/auth/user gives me a Django 404 error

The 404 errors lead me to suspect my URLconf is wrong, but all I did was uncomment the built-in lines. The relevant sections read:

# Uncomment the admin/doc line below to enable admin documentation:
(r'^admin/doc/', include('django.contrib.admindocs.urls')),

# Uncomment the next line to enable the admin:
(r'^admin/', include(admin.site.urls)), 

And I have no idea what to make of the blank pages. Do I need to provide some extra meta information somewhere, like I know you need to provide the get_absolute_url on models for some of the admin features to work right?

Even if no one knows the answer, any documentation on the admin docs feature would be useful -- I've been Google all over (and searching StackOverflow) and this feature seems very little-documented.

Thanks!

You need to add 'django.contrib.admindocs' to your INSTALLED_APPS in settings.py. It should already be there and commented out. Though it would be nice if the comment in urls.py mentioned it ... Source.

I've never looked at the views admin doc pages before -- I've never had a need to. B4ut you're right, they seem to be -- lacking in potential features.

If you give your views functions docstrings (documentation), that content will appear on your "blank pages".

Most -- no, all -- of the admin sites views are actually decorated member methods of admin.sites.AdminSite. I looked around, and a view of mine which uses a decorator also suffers from the 404.

The view responsible for view details starts:

def view_detail(request, view):
    if not utils.docutils_is_available:
        return missing_docutils_page(request)

    mod, func = urlresolvers.get_mod_func(view)
    try:
        view_func = getattr(import_module(mod), func)
    except (ImportError, AttributeError):
        raise Http404
    title, body, metadata = utils.parse_docstring(view_func.__doc__)
    ...

You can see it tries to import the view to get info from it; if the view is actually a decorator (which probably used an internal function to wrap the real view), it won't be able to import it. eg, if you do from django.contrib.admin.sites import index in a django shell, you'll get an ImportError, whereas django.contrib.admin.site.index (note the singular site) is a:

<bound method AdminSite.index of <django.contrib.admin.sites.AdminSite object at 0x...>>

Further, that last line in my snippet seems to indicate that there's a capability for finer control over what shows up on those pages, if you care to figure out the template that util.parse_docstring uses.