Opened 13 years ago

Last modified 24 hours ago

#15396 new Bug

full path to modules in documentation inconsistently referenced

Reported by: slinkp@… Owned by:
Component: Documentation Version: dev
Severity: Normal Keywords:
Cc: James Pic, Ülgen Sarıkavak Triage Stage: Accepted
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

To enable GzipMiddleware, you have to add to your MIDDLEWARE_CLASSES:
'django.middleware.gzip.GZipMiddleware'

... which you'd have to work out by guesswork or reading the source, as it's not
specified on either http://docs.djangoproject.com/en/dev/ref/middleware/#module-django.middleware.gzip
or http://docs.djangoproject.com/en/dev/topics/http/middleware/#activating-middleware

There are probably others similarly undocumented, but I haven't audited them all.

Change History (17)

comment:1 by Russell Keith-Magee, 13 years ago

Component: UncategorizedDocumentation
Triage Stage: UnreviewedAccepted

comment:2 by Łukasz Rekucki, 13 years ago

Severity: Normal
Type: Bug

comment:3 by James Pic, 13 years ago

Cc: James Pic added
Easy pickings: unset
Version: 1.2

The path is documented on http://docs.djangoproject.com/en/1.3/topics/cache/#other-optimizations

Also, the module is documented in ref/middleware.txt, but it's not rendered in http://docs.djangoproject.com/en/dev/ref/middleware/#django.middleware.gzip.GZipMiddleware:

GZIP middleware
---------------

.. module:: django.middleware.gzip
   :synopsis: Middleware to serve gziped content for performance.

.. class:: GZipMiddleware

So i guess that would be a bug in the documentation renderer, not the documentation contents.

comment:4 by Aymeric Augustin, 12 years ago

UI/UX: unset

Change UI/UX from NULL to False.

comment:5 by Claude Paroz, 12 years ago

The add_module_names directive in docs/conf.py is currently set to False. If set to True, it would prepend the module path to the class. However, there are almost 200 module:: or currentmodule:: directives in the documentation, so I don't know if displaying the full path is always the desired effect.

comment:6 by Preston Holmes, 11 years ago

Summary: full path to GzipMiddleware undocumentedfull path to modules in documentation inconsistently referenced
Version: master

#19281 was a dupe for the more general sense, so I've updated the summary to be a bit more generic.

This has always something that has bugged me - and has been somewhere on my todo list since this tweet crossed my path:

https://twitter.com/doughellmann/statuses/248093601886765056 :
"Python Dev Pro-tip: Include the import statements in each example in your documentation. Your casual readers will thank you."

So there are two places to add this information:

As information or heading in the reference documentation - and in code listings.

comment:7 by Aymeric Augustin, 11 years ago

#19864 was another duplicate.

comment:8 by davesque, 11 years ago

From duplicate #19864, I had thought about Carl's suggestion that the heading should instead state the full resource path instead of just the resource name:

class django.template.response.TemplateResponse
instead of
class TemplateResponse

I wasn't sure if that would sometimes be too verbose. That's why I had suggested the alternative:

module: django.template.response
class TemplateResponse

However, I prefer Carl's suggestion if it doesn't disrupt the layout of the current docs too much.

comment:9 by Daniele Procida, 10 years ago

I agree that simply turning on display of modules with add_module_names would be a rather scattershot approach. Module names are not always provided anyway.

I think that the best approach would be for code samples to include imports, or at least the first one of a batch of them.

Similarly, if an object's path is not clear from its reasonably immediate context, then it should be spelled out in full the first time it's introduced in its reference documentation.

If there's a list of objects all from the same module, the module can be mentioned once at the top of the list.

comment:10 by denis_g@…, 10 years ago

It would be very nice to have this option somehow available, but disabled by default if you think it's not good to enable it for all.

For instance, full resource path may be rendered with the display: none style, so people who need it may enable it with the simple CSS rule.

Or there may be some kind of JavaScript magic, which would display the full resource path on user click or hover, or whatever else.

comment:11 by Tim Graham, 9 years ago

One option to display the full module path is something like this:

  • docs/ref/models/expressions.txt

    diff --git a/docs/ref/models/expressions.txt b/docs/ref/models/expressions.txt
    index f74c4f2..d0b4a14 100644
    a b output value.  
    360360``ExpressionWrapper()`` expressions
    361361-----------------------------------
    362362
    363 .. class:: ExpressionWrapper(expression, output_field)
     363.. class:: django.db.models.ExpressionWrapper(expression, output_field)
     364    :module:
    364365
    365366.. versionadded:: 1.8
    366367

comment:12 by Mar Sánchez, 4 years ago

Owner: changed from nobody to Mar Sánchez
Status: newassigned

I just added a little note about adding the full path of the class in the settings file

comment:13 by Mariusz Felisiak <felisiak.mariusz@…>, 4 years ago

In f1d4a540:

Refs #15396 -- Mentioned full path to GZipMiddleware in documentation.

comment:14 by Mariusz Felisiak <felisiak.mariusz@…>, 4 years ago

In 9fa6c737:

[3.0.x] Refs #15396 -- Mentioned full path to GZipMiddleware in documentation.

Backport of f1d4a540b29c6766b988852bc302ac036a2d82e2 from master

comment:15 by Mariusz Felisiak <felisiak.mariusz@…>, 4 years ago

In f5f4c28b:

[2.2.x] Refs #15396 -- Mentioned full path to GZipMiddleware in documentation.

Backport of f1d4a540b29c6766b988852bc302ac036a2d82e2 from master

comment:16 by Mariusz Felisiak, 3 years ago

Owner: Mar Sánchez removed
Status: assignednew

comment:17 by Ülgen Sarıkavak, 24 hours ago

Cc: Ülgen Sarıkavak added
Note: See TracTickets for help on using tickets.
Back to Top