Opened 16 years ago

Closed 16 years ago

Last modified 12 years ago

#8496 closed (fixed)

django.contrib.admindoc no reference in documentation

Reported by: Eric Vander Weele Owned by: Eric Vander Weele
Component: Documentation Version: dev
Severity: Keywords: admindoc
Cc: Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

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.

Attachments (2)

8496.diff (1.3 KB ) - added by Eric Vander Weele 16 years ago.
8496_AUTHORS.diff (315 bytes ) - added by Eric Vander Weele 16 years ago.

Download all attachments as: .zip

Change History (13)

comment:1 by Jacob, 16 years ago

Component: Admin interfaceDocumentation
Triage Stage: UnreviewedAccepted

comment:2 by Julien Phalip, 16 years ago

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.

comment:3 by Karen Tracey, 16 years ago

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.

comment:4 by Eric Vander Weele, 16 years ago

Has patch: set

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.

comment:5 by Eric Vander Weele, 16 years ago

Summary: django.contrib.admindoc no refernce in documentationdjango.contrib.admindoc no reference in documentation

comment:6 by Eric Vander Weele, 16 years ago

Owner: changed from nobody to Eric Vander Weele

comment:7 by Eric Vander Weele, 16 years ago

Status: newassigned

in reply to:  3 comment:8 by Julien Phalip, 16 years ago

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

by Eric Vander Weele, 16 years ago

Attachment: 8496.diff added

comment:9 by Eric Vander Weele, 16 years ago

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

comment:10 by Jacob, 16 years ago

Resolution: fixed
Status: assignedclosed

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

by Eric Vander Weele, 16 years ago

Attachment: 8496_AUTHORS.diff added

comment:11 by Jacob, 12 years ago

milestone: 1.0

Milestone 1.0 deleted

Note: See TracTickets for help on using tickets.
Back to Top