Code

Opened 3 years ago

Closed 3 years ago

#17145 closed Bug (invalid)

Documentation lacking import paths

Reported by: drozzy@… Owned by: nobody
Component: Documentation Version: 1.3
Severity: Normal Keywords: imports
Cc: Triage Stage: Unreviewed
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: yes UI/UX: no

Description

There is no way to know, from where to import classes when reading the documentation.

For example, on the generic views doc page:
https://docs.djangoproject.com/en/dev/ref/class-based-views/
where does one import TemplateResponseMixin from?

I mean it should enable me to write something like this:
from django.[missing] import TemplateResponseMixin

But currently there is no way in the docs, to find the [missing] parameter! One has to either browse the source code, or search google in hopes that there are some examples online!

This has always been a problem throughout the Django docs. Is there a way to consistently document this?

Attachments (0)

Change History (3)

comment:1 Changed 3 years ago by drozzy@…

  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset

Took me a while to "guess" that FormMixin resides in:
django.views.generic.edit.FormMixin

comment:2 Changed 3 years ago by aaugustin

where does one import TemplateResponseMixin from?

The reference page (your link) begins with a link to the topic page, where you can see that class-based generic views live in django.views.generic.


This has always been a problem throughout the Django docs.

I agree that import paths must be included in the docs. But I don't find it realistic to keep a ticket that basically says "read all the docs and add missing import paths" — especially when that ticket doesn't come with a patch, so I'm reluctant to accept this.


Is there a way to consistently document this?

The usual approach is to include import statement in code snippets.

comment:3 Changed 3 years ago by ptone

  • Resolution set to invalid
  • Status changed from new to closed

I'll second the idea that a blanket ticket isn't useful. I agree the sample code should be more complete with imports often these imports are only listed in the first of several related snippets - but that is better than nothing.

By all means open individual tickets for specific examples.

Add Comment

Modify Ticket

Change Properties
<Author field>
Action
as closed
as The resolution will be set. Next status will be 'closed'
The resolution will be deleted. Next status will be 'new'
Author


E-mail address and user name can be saved in the Preferences.

 
Note: See TracTickets for help on using tickets.