Re: [Django] #35461: Tutorial instructions for adding django-debug-toolbar are misleading.

[Django]

#35461: Tutorial instructions for adding django-debug-toolbar are misleading.
-------------------------------+------------------------------------
Reporter: dawbert | Owner: nobody
Type: Bug | Status: new
Component: Documentation | Version: 5.0
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------+------------------------------------
Comment (by Timothy Schilling):

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
--
Ticket URL: <https://code.djangoproject.com/ticket/35461#comment:2>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.

[Django]

#35461: Tutorial instructions for adding django-debug-toolbar are misleading.

-------------------------------+------------------------------------------
Reporter: dawbert | Owner: Saksham Mathur
Type: Bug | Status: assigned

Component: Documentation | Version: 5.0
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0

-------------------------------+------------------------------------------
Changes (by Saksham Mathur):

* owner: nobody => Saksham Mathur
* status: new => assigned

Comment:

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?
--
Ticket URL: <https://code.djangoproject.com/ticket/35461#comment:3>

[Django]

#35461: Tutorial instructions for adding django-debug-toolbar are misleading.

-------------------------------------+-------------------------------------
Reporter: dawbert | Owner: Saksham
Type: | Mathur
Cleanup/optimization | Status: assigned

Component: Documentation | Version: 5.0
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0

-------------------------------------+-------------------------------------
Changes (by Mariusz Felisiak):

* cc: Mariusz Felisiak (added)
* type: Bug => Cleanup/optimization

Comment:

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.
--
Ticket URL: <https://code.djangoproject.com/ticket/35461#comment:4>

[Django]

#35461: Tutorial instructions for adding django-debug-toolbar are misleading.

--------------------------------------+------------------------------------
Reporter: dawbert | Owner: (none)
Type: Cleanup/optimization | Status: new

Component: Documentation | Version: 5.0
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0

--------------------------------------+------------------------------------
Changes (by Saksham Mathur):

* owner: Saksham Mathur => (none)
* status: assigned => new

--
Ticket URL: <https://code.djangoproject.com/ticket/35461#comment:5>

[Django]

#35461: Tutorial instructions for adding django-debug-toolbar are misleading.
--------------------------------------+------------------------------------
Reporter: dawbert | Owner: (none)
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: 5.0
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
--------------------------------------+------------------------------------

Changes (by Sarah Boyce):

* cc: Adam Johnson (added)

Comment:

Replying to [comment:4 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
--
Ticket URL: <https://code.djangoproject.com/ticket/35461#comment:6>

[Django]

#35461: Tutorial instructions for adding django-debug-toolbar are misleading.
--------------------------------------+------------------------------------
Reporter: dawbert | Owner: (none)
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: 5.0
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
--------------------------------------+------------------------------------

Changes (by Ryan Cheley):

* cc: Ryan Cheley (added)

--
Ticket URL: <https://code.djangoproject.com/ticket/35461#comment:7>

[Django]

#35461: Tutorial instructions for adding django-debug-toolbar are misleading.

-------------------------------------+-------------------------------------
Reporter: dawbert | Owner: Rosana
Type: | Rufer
Cleanup/optimization | Status: assigned

Component: Documentation | Version: 5.0
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0

-------------------------------------+-------------------------------------
Changes (by Rosana Rufer):

* owner: (none) => Rosana Rufer

* status: new => assigned

Comment:

I've been working on this and looking and testing the issue from different
perspectives and I've got a proposal.
Here's a summary on the thread and reasoning:
https://www.notion.so/Tutorial-instructions-for-adding-django-debug-
toolbar-are-misleading-1f1429081df4473cb5bad80790cc4176

**Total options proposed by participants:**

- **Option A** - Add the body tag in earlier pages.
- **Option A.2** - A 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
--
Ticket URL: <https://code.djangoproject.com/ticket/35461#comment:8>

[Django]

#35461: Tutorial instructions for adding django-debug-toolbar are misleading.
-------------------------------------+-------------------------------------
Reporter: dawbert | Owner: Rosana
Type: | Rufer
Cleanup/optimization | Status: assigned
Component: Documentation | Version: 5.0
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted

Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Changes (by Rosana Rufer):

* has_patch: 0 => 1


Old description:

> 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.

New description:

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

--
--
Ticket URL: <https://code.djangoproject.com/ticket/35461#comment:9>

[Django]

#35461: Tutorial instructions for adding django-debug-toolbar are misleading.
-------------------------------------+-------------------------------------
Reporter: dawbert | Owner: Rosana
Type: | Rufer
Cleanup/optimization | Status: assigned
Component: Documentation | Version: 5.0
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 1

Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Sarah Boyce):

* needs_better_patch: 0 => 1

--
Ticket URL: <https://code.djangoproject.com/ticket/35461#comment:10>

[Django]

#35461: Tutorial instructions for adding django-debug-toolbar are misleading.
-------------------------------------+-------------------------------------
Reporter: dawbert | Owner: Rosana
Type: | Rufer
Cleanup/optimization | Status: assigned
Component: Documentation | Version: 5.0
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 0

Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Changes (by Sarah Boyce):

* needs_better_patch: 1 => 0

--
Ticket URL: <https://code.djangoproject.com/ticket/35461#comment:11>

[Django]

#35461: Tutorial instructions for adding django-debug-toolbar are misleading.
-------------------------------------+-------------------------------------
Reporter: dawbert | Owner: Rosana
Type: | Rufer
Cleanup/optimization | Status: assigned
Component: Documentation | Version: 5.0
Severity: Normal | Resolution:

Keywords: | Triage Stage: Ready for
| checkin

Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Changes (by Sarah Boyce):

* stage: Accepted => Ready for checkin

--
Ticket URL: <https://code.djangoproject.com/ticket/35461#comment:12>

[Django]

#35461: Tutorial instructions for adding django-debug-toolbar are misleading.
-------------------------------------+-------------------------------------
Reporter: dawbert | Owner: Rosana
Type: | Rufer

Cleanup/optimization | Status: closed
Component: Documentation | Version: 5.0
Severity: Normal | Resolution: fixed

Keywords: | Triage Stage: Ready for
| checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Sarah Boyce <42296566+sarahboyce@…>):

* resolution: => fixed
* status: assigned => closed

Comment:

In [changeset:"72b7aecbbfbec0ceb1a829eef82a68d7283df604" 72b7aecb]:
{{{#!CommitTicketReference repository=""
revision="72b7aecbbfbec0ceb1a829eef82a68d7283df604"
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.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/35461#comment:13>

[Django]

#35461: Tutorial instructions for adding django-debug-toolbar are misleading.
-------------------------------------+-------------------------------------
Reporter: dawbert | Owner: Rosana
Type: | Rufer
Cleanup/optimization | Status: closed
Component: Documentation | Version: 5.0
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Ready for
| checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Sarah Boyce <42296566+sarahboyce@…>):

In [changeset:"9143ecfd8b06ab8a63cb52074624102c34dec0a1" 9143ecf]:
{{{#!CommitTicketReference repository=""
revision="9143ecfd8b06ab8a63cb52074624102c34dec0a1"
[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.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/35461#comment:14>