Opened 7 years ago

Closed 7 years ago

Last modified 4 years ago

#8496 closed (fixed)

django.contrib.admindoc no reference in documentation

Reported by: ericvw Owned by: ericvw
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 ericvw 7 years ago.
8496_AUTHORS.diff (315 bytes) - added by ericvw 7 years ago.

Download all attachments as: .zip

Change History (13)

comment:1 Changed 7 years ago by jacob

  • Component changed from Admin interface to Documentation
  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset
  • Triage Stage changed from Unreviewed to Accepted

comment:2 Changed 7 years ago by julien

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 follow-up: Changed 7 years ago by kmtracey

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 7 years ago by ericvw

  • 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 7 years ago by ericvw

  • Summary changed from django.contrib.admindoc no refernce in documentation to django.contrib.admindoc no reference in documentation

comment:6 Changed 7 years ago by ericvw

  • Owner changed from nobody to ericvw

comment:7 Changed 7 years ago by ericvw

  • Status changed from new to assigned

comment:8 in reply to: ↑ 3 Changed 7 years ago by julien

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 7 years ago by ericvw

comment:9 Changed 7 years ago by ericvw

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

comment:10 Changed 7 years ago by jacob

  • Resolution set to fixed
  • Status changed from assigned to closed

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

Changed 7 years ago by ericvw

comment:11 Changed 4 years ago by jacob

  • milestone 1.0 deleted

Milestone 1.0 deleted

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