Code

#19864 closed Cleanup/optimization (duplicate)

No standard method of indicating import paths in documentation

Reported by: davesque@… Owned by: nobody
Component: Documentation Version: 1.4
Severity: Normal Keywords: import paths
Cc: Triage Stage: Accepted
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

I've been using Django for about a year now and there's something about the Django documentation that's always seemed inconvenient to me.

If you're ever reading about a class, function, etc. in docs, it's rarely obvious where to import that resource from. The module path is almost never indicated a consistent or obvious way.

For example, take a look at this doc page:

https://docs.djangoproject.com/en/dev/ref/template-response/

What I would expect is that, directly above this heading or somewhere similar, the full import path of the class would be indicated in some way. Perhaps like this:

...
module: django.template.response

class SimpleTemplateResponse
...

...or something like that. I'm aware of the hash links next to each heading which contain the full import path. This is fine, but that information should not be hidden. It should be on the page in plain view.

I think we should launch an initiative to fix this problem with usability in the Django docs.

Attachments (0)

Change History (4)

comment:1 Changed 14 months ago by davesque@…

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

It seems what I was talking about above, with the full import path being present in the hash link href, is not always the case. Take this link, for example. In that case, the import path is indicated somewhere on the page, but you have to search for it.

comment:2 Changed 14 months ago by davesque@…

  • Type changed from Uncategorized to Cleanup/optimization

comment:3 Changed 14 months ago by carljm

  • Triage Stage changed from Unreviewed to Accepted

I agree that it would be better if the full import path were more consistently available in the reference documentation. There will need to be some decisions made about how/where to display it (for instance, in your example case I think it would be even clearer if it just said class django.template.response.SimpleTemplateResponse rather than class SimpleTemplateResponse.)

The next thing needed to get this "initiative" rolling is a proposed patch to the docs!

comment:4 Changed 14 months ago by aaugustin

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

This is a duplicate of #19281 and #15396.

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.