Opened 6 months ago

Closed 5 months ago

Last modified 5 months ago

#35461 closed Cleanup/optimization (fixed)

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

Reported by: dawbert Owned by: Rosana Rufer
Component: Documentation Version: 5.0
Severity: Normal Keywords:
Cc: Timothy Schilling, Mariusz Felisiak, Adam Johnson, Ryan Cheley Triage Stage: Ready for checkin
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description (last modified by Rosana Rufer)

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.

https://docs.djangoproject.com/en/5.0/intro/tutorial08/#installing-django-debug-toolbar

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.

Patch: https://github.com/django/django/pull/18285

Change History (14)

comment:1 by Sarah Boyce, 6 months 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, 6 months 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, 6 months 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, 5 months 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, 5 months ago

Owner: Saksham Mathur removed
Status: assignednew

in reply to:  4 comment:6 by Sarah Boyce, 5 months ago

Cc: Adam Johnson added

Replying to Mariusz Felisiak:

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.

Looks like this note was added based off this forum question: https://forum.djangoproject.com/t/are-html-tags-needed-in-templates/806/1
Personally, I still think a clarification is required as this note says "in your own projects" rather than that this is requirement for part 8 of the tutorial to work as expected

comment:7 by Ryan Cheley, 5 months ago

Cc: Ryan Cheley added

comment:8 by Rosana Rufer, 5 months ago

Owner: set to Rosana Rufer
Status: newassigned

I've been working on this and looking and testing the issue from different perspectives and I've got a proposal.

Total options proposed by participants:

  • Option A - Add the body tag in earlier pages.
    • Option A.2 - Add a new step using template inheritance.
  • Option B - Use a different addon as example.
  • Option C - Suggest looking at the toolbar in /admin and explain what needs tweaking for it to work in /polls.

Discussion timeline:

  • Dawbert (Reporter) says: Following the tutorial gives wrong results when installing django-debug-toolbar as templates need to be wrapped in complete HTML but the tutorial doesn’t do it for brevity. Proposing options A and B
  • Sarah agrees Django documentation needs tweaking. Mentions the body tag requirement is already documented in the official django-toolbar app.
  • Timothy offers options A, A.2 and C

My Conclusion: It’s worth doing option C.

Reasoning:

  • The main goal of this section is to learn how to add a package in the first place and a bit of django-debug-toolbar in second place. Option C provides both quickly in /admin, additionally providing a pointer on how to see such toolbar in /polls
  • Most people following this tutorial will trip on this step for many reasons* and it’s worth improving this.

Pull Request with proposed change: https://github.com/django/django/pull/18285

📝 Notion with extended reasoning here: https://www.notion.so/Tutorial-instructions-for-adding-django-debug-toolbar-are-misleading-1f1429081df4473cb5bad80790cc4176

Last edited 5 months ago by Rosana Rufer (previous) (diff)

comment:9 by Rosana Rufer, 5 months ago

Description: modified (diff)
Has patch: set

comment:10 by Sarah Boyce, 5 months ago

Patch needs improvement: set

comment:11 by Sarah Boyce, 5 months ago

Patch needs improvement: unset

comment:12 by Sarah Boyce, 5 months ago

Triage Stage: AcceptedReady for checkin

comment:13 by Sarah Boyce <42296566+sarahboyce@…>, 5 months ago

Resolution: fixed
Status: assignedclosed

In 72b7aecb:

Fixed #35461 -- Updated misleading django-debug-toolbar instructions.

The DjDT "handle" isn't visible on the polls application as the templates
are missing <body> tags for brevity.

comment:14 by Sarah Boyce <42296566+sarahboyce@…>, 5 months ago

In 9143ecf:

[5.1.x] Fixed #35461 -- Updated misleading django-debug-toolbar instructions.

The DjDT "handle" isn't visible on the polls application as the templates
are missing <body> tags for brevity.

Backport of 72b7aecbbfbec0ceb1a829eef82a68d7283df604 from main.

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