Opened 4 weeks ago

Last modified 12 days ago

#35461 new Cleanup/optimization

Tutorial instructions for adding django-debug-toolbar are misleading.

Reported by: dawbert Owned by:
Component: Documentation Version: 5.0
Severity: Normal Keywords:
Cc: Timothy Schilling, Mariusz Felisiak Triage Stage: Accepted
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no


Hey folks!

The instructions in step 8 of the tutorial recommend adding the django-debug-toolbar as a way to understand third-party apps, etc, but it doesn't work without additional changes to the mysite project.

It finishes by saying, "Once installed, you should be able to see the DjDT “handle” on the right side of the browser window when you refresh the polls application."

However, the panel only shows if the view has a "</body>" tag, which none of the views you write have.

Suggest either adding the body tag into the earlier pages, updating the documentation to say you need to add them, or using a different addon as an example.

Change History (5)

comment:1 by Sarah Boyce, 4 weeks ago

Cc: Timothy Schilling added
Summary: Tutorial instructions for adding third-party app don't workTutorial instructions for adding django-debug-toolbar are misleading.
Triage Stage: UnreviewedAccepted
Type: UncategorizedBug

Hi dawbert, thank you for raising! I agree this is not the best experience for a tutorial and the docs are misleading.
This body tag requirement is documented in the django-debug-toolbar docs so I don't think this is a bug in django-debug-toolbar, we should make a tweak 👍

comment:2 by Timothy Schilling, 4 weeks ago

Oh, I didn't realize there wasn't an actual valid HTML template earlier in the tutorial.

I see three options right now:

  1. Add steps manipulating one view's response to include the proper HTML tags
  2. Include a new advanced tutorial demoing template inheritance where it uses the proper HTML tags
  3. Refer the user to the admin interface on their app to see the toolbar and explain why it doesn't show for the other views

comment:3 by Saksham Mathur, 4 weeks ago

Owner: changed from nobody to Saksham Mathur
Status: newassigned

This can be fixed after adding body tag in html files, we can add documentation citing that body tag is required for toolbar handle.
Should I pick this issue?

comment:4 by Mariusz Felisiak, 2 weeks ago

Cc: Mariusz Felisiak added
Type: BugCleanup/optimization

This was already raised and clarified in tutorial 3:

"To make the tutorial shorter, all template examples use incomplete HTML. In your own projects you should use complete HTML documents."

Check out 26be53dd89cef46746b4a67cbc0bb29665e999a6.

comment:5 by Saksham Mathur, 12 days ago

Owner: Saksham Mathur removed
Status: assignednew
Note: See TracTickets for help on using tickets.
Back to Top