Opened 8 years ago

Closed 8 years ago

Last modified 5 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: master
Severity: Keywords: admindoc
Cc: Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: UI/UX:

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 8 years ago.
8496_AUTHORS.diff (315 bytes) - added by Eric Vander Weele 8 years ago.

Download all attachments as: .zip

Change History (13)

comment:1 Changed 8 years ago by Jacob

Component: Admin interfaceDocumentation
Needs documentation: unset
Needs tests: unset
Patch needs improvement: unset
Triage Stage: UnreviewedAccepted

comment:2 Changed 8 years ago by 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.

comment:3 Changed 8 years ago by 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.

comment:4 Changed 8 years ago by Eric Vander Weele

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 Changed 8 years ago by Eric Vander Weele

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

comment:6 Changed 8 years ago by Eric Vander Weele

Owner: changed from nobody to Eric Vander Weele

comment:7 Changed 8 years ago by Eric Vander Weele

Status: newassigned

comment:8 in reply to:  3 Changed 8 years ago by 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

Changed 8 years ago by Eric Vander Weele

Attachment: 8496.diff added

comment:9 Changed 8 years ago by Eric Vander Weele

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

comment:10 Changed 8 years ago by Jacob

Resolution: fixed
Status: assignedclosed

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

Changed 8 years ago by Eric Vander Weele

Attachment: 8496_AUTHORS.diff added

comment:11 Changed 5 years ago by Jacob

milestone: 1.0

Milestone 1.0 deleted

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