Change in Sphinx rendering of current module

[stherrien]

I would like to add import statements to the documentation under the class to make things easier to find currently the docs offer an index of all the modules and when followed the doc of the class definition doesn't contain the import statements these are very useful in the documentation and I think they should exist where they currently do not. example would be the django file object docs page ​http://docs.djangoproject.com/en/1.1/ref/files/file/#ref-files-file it currently doesn't show any import statements to show the user where this module exists.

[stherrien]

patch for the file object doc page

[Russell Keith-Magee]

Sphinx provides much better ways to do this. You don't need to manually include an include statement like the one you describe, you need to make the ".. class::" declaration fully qualified, or set the package context so that a classname-only declaration knows the right path.

[stherrien]

Russel,

I think I understand what your looking for I think the second diff will give you what you need for this fix and I would like to go through all of the docs and add these fully qualified class paths.
example instead of this".. class:: File(file_object)" you want this ".. class:: django.core.files.File(file_object)" is that correct?

-shawn

[stherrien]

full qualified class path

[Russell Keith-Magee]

Broadly speaking, yes, but In this specific case, no. Like I said, Django can maintain the current package as context, and in this case, it already is.

.. currentmodule:: django.core.files 
.. class:: File(file_object) 

and

.. class:: django.core.files File(file_object) 

are equivalent.

That is, Sphinx already has all the metadata it requires. If the rendering isn't exploiting that metadata, that's a separate issue. There may be places in code where classes aren't fully marked up, in which case, yes -- the ..class decorations need to be corrected.

Closing wontfix because the specific example you have given doesn't require any modification (side note - please generate patches from the root of the source tree, not just of a single file)

If you want to propose changing the Sphinx rendering, or can provide a patch that identifies classes that don't have the right class markup, please reopen.

[stherrien]

I purpose changing the Sphinx rendering of current modules I think this is helpful to show the full paths in the docs.

[stherrien]

change in conf to show current modules in docs

[Russell Keith-Magee]

Marking accepted, because the specific instance in the files docs is clearly a problem. However, the proposed solution isn't ideal -- the reason add_module_names is currently set to False is because there are many places where the repeated module name doesn't aid readability (for example, in the documentation on testing utilities -- topics/testing.html#topics-testing)

[Gabriel Hurley]

(In [14339]) Fixed #13040 -- Added info on where to import File class from to File reference docs, and improved Sphinx formatting. Thanks to stherrien for the report.

[Gabriel Hurley]

(In [14340]) [1.2.X] Fixed #13040 -- Added info on where to import File class from to File reference docs, and improved Sphinx formatting. Thanks to stherrien for the report.

Backport of [14339] from trunk.