Opened 5 years ago

Closed 4 years ago

Last modified 4 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 5 years ago.
patch for the file object doc page
files.2.diff (350 bytes) - added by stherrien 5 years ago.
full qualified class path
conf.diff (455 bytes) - added by stherrien 5 years ago.
change in conf to show current modules in docs

Download all attachments as: .zip

Change History (14)

Changed 5 years ago by stherrien

patch for the file object doc page

comment:1 Changed 5 years ago by anonymous

  • Component changed from Uncategorized to Documentation
  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset

comment:2 Changed 5 years ago by anonymous

  • Has patch set

comment:3 Changed 5 years ago by russellm

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

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 5 years ago by stherrien

  • Resolution wontfix deleted
  • Status changed from closed to reopened

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 5 years ago by stherrien

full qualified class path

comment:5 Changed 5 years ago by anonymous

  • Cc shawntherrien@… added

comment:6 Changed 5 years ago by russellm

  • Resolution set to wontfix
  • Status changed from reopened to closed

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 5 years ago by stherrien

  • Resolution wontfix deleted
  • Status changed from closed to reopened
  • Summary changed from Would like to add import statments for class documentation where needed to Change 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 5 years ago by stherrien

change in conf to show current modules in docs

comment:8 Changed 5 years ago by russellm

  • Patch needs improvement set
  • Triage Stage changed from Unreviewed to Accepted

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 5 years ago by anonymous

  • Owner changed from nobody to stherrien
  • Status changed from reopened to new

comment:10 Changed 4 years ago by gabrielhurley

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

(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 4 years ago by gabrielhurley

(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