django.contrib.admindoc no reference in documentation

[Eric Vander Weele]

The are no references in the current Django documentation (or in a fresh project) that informs that django.contrib.admindoc must be be in INSTALLED_APPS in order to enable the documentation for the admin interface.

[Julien Phalip]

IMHO, this ticket should be closed as invalid. At least, I don't think it should be under the 1.0 milestone. Since Jacob has already accepted it, I won't resolve the ticket myself and I'll just add some comments below.

As far as I can see, admindocs is not described anywhere in the doc, including the refactored one. It only referenced in the tutorial2 (and in fact, not even directly) and in the project template's settings.py.

That application, as other contrib apps, would deserve a whole page for itself. But at this stage I see no purpose for specifying the necessity to include the app in INSTALLED_APPS. That's a trivial information that would attract too much attention to admindocs in the tutorial.

So, I'd close this ticket as invalid. Then, for whoever's interested to work on the docs:

• Create a new one with a patch adding a new page that explains what admindocs is about.
• Finally, add a link in the 'Add-on (“contrib”) applications' section to that new page.

The same thing should eventually be done for every contrib apps.

[Karen Tracey]

Invalid? Users are already tripping over the lack of this information in the docs:

​http://groups.google.com/group/django-users/browse_thread/thread/7fdbb7548d2665fe/d7f29498c5cabcfc

There's a link at the top of every admin page that says 'Documentation'. Unless we tell users somewhere to add this line to INSTALLED_APPS, then they have no way to know how to make that link work. By default it displays a TemplateDoesNotExist error. Just because it didn't need to be documented before (because it Just Worked) doesn't mean doc shouldn't be written for it now that it doesn't do so.

[Eric Vander Weele]

I agree that it shouldn't have its own entire contrib apps page. It really is just an 'app' that must be put in INSTALLED_APPS for the admin docs to work. If this ticket doesn't go through, the documentation link in the admin interface should be removed since it will cause confusion.

I couldn't find it referenced in the project template's settings.py.

I would recommend replacing in the urls.py:
# Uncomment the next line to enable admin documentation:

I have included a patch with an updated comment for the project template urls.py.

I had to ask in the IRC channels how to enable the documentation which shouldn't
need to happen under normal circumstances.

[Julien Phalip]

Replying to kmtracey:

Invalid? Users are already tripping over the lack of this information in the docs:
[...]
Just because it didn't need to be documented before (because it Just Worked) doesn't mean doc shouldn't be written for it now that it doesn't do so.

Sorry, I had missed that this was a new issue and that it was causing trouble to some users. I should have checked.

If following the same approach as in ericvw's patch, django/docs/intro/tutorial02.txt should also be fixed. It contains a snippet taken from the default project template.

​http://docs.djangoproject.com/en/dev/intro/tutorial02/#activate-the-admin-site

[Eric Vander Weele]

I updated the patch so the the tutorial02.txt matches. Thanks julien.

[Jacob]

(In [8859]) Fixed #8496: added a note about admindocs to the project template and the tutorial. Thanks, ericvw.

[Jacob]

Milestone 1.0 deleted