Opened 7 years ago

Closed 6 years ago

Last modified 6 years ago

#13040 closed (fixed)

Change in Sphinx rendering of current module

Reported by: stherrien Owned by: stherrien
Component: Documentation Version: 1.1
Severity: Keywords:
Cc: shawntherrien@… Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: yes
Easy pickings: UI/UX:

Description

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.

Attachments (3)

files.diff (334 bytes) - added by stherrien 7 years ago.
patch for the file object doc page
files.2.diff (350 bytes) - added by stherrien 7 years ago.
full qualified class path
conf.diff (455 bytes) - added by stherrien 7 years ago.
change in conf to show current modules in docs

Download all attachments as: .zip

Change History (14)

Changed 7 years ago by stherrien

Attachment: files.diff added

patch for the file object doc page

comment:1 Changed 7 years ago by anonymous

Component: UncategorizedDocumentation

comment:2 Changed 7 years ago by anonymous

Has patch: set

comment:3 Changed 7 years ago by Russell Keith-Magee

Resolution: wontfix
Status: newclosed

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.

comment:4 Changed 7 years ago by stherrien

Resolution: wontfix
Status: closedreopened

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

Changed 7 years ago by stherrien

Attachment: files.2.diff added

full qualified class path

comment:5 Changed 7 years ago by anonymous

Cc: shawntherrien@… added

comment:6 Changed 7 years ago by Russell Keith-Magee

Resolution: wontfix
Status: reopenedclosed

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.

comment:7 Changed 7 years ago by stherrien

Resolution: wontfix
Status: closedreopened
Summary: Would like to add import statments for class documentation where neededChange in Sphinx rendering of current module

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

Changed 7 years ago by stherrien

Attachment: conf.diff added

change in conf to show current modules in docs

comment:8 Changed 7 years ago by Russell Keith-Magee

Patch needs improvement: set
Triage Stage: UnreviewedAccepted

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)

comment:9 Changed 7 years ago by anonymous

Owner: changed from nobody to stherrien
Status: reopenednew

comment:10 Changed 6 years ago by Gabriel Hurley

Resolution: fixed
Status: newclosed

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

comment:11 Changed 6 years ago by 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.

Note: See TracTickets for help on using tickets.
Back to Top