Opened 11 years ago

Closed 10 years ago

Last modified 10 years ago

#11152 closed (fixed)

Some classes missing in documentation (Template docs)

Reported by: ben Owned by: nobody
Component: Documentation Version: master
Severity: Keywords: autodoc intersphinx
Cc: Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no


I want to use intersphinx to connect up my documentation with django's. #10315 has made the .inv file available (and I've added a little bit of documentation there on how to make it work) but I still can't get to django.template.Context. In the docs there's a reference to:

Rendering a context¶

Once you have a compiled Template object, you can render a context -- or multiple contexts -- with it. The Context class lives at django.template.Context

However this class isn't hyperlinked (and as such a central class in django it'd be nice if its API was documented).

So a couple of questions here:

  1. Is this a one off or is django not making full use of sphinx?
  2. Is there a convention for structuring the documentation WRT autodoc stuff and narrative docs (I was lurking around when the initial move to sphinx was made but I guess I'm a little out of touch)
  3. Actually I just grepped (actually grinned :-D) and I can't find any references to autodoc'd stuff. Is there a reason why not?

I'm happy to add this to the docs and provide a patch, but figured I'd also raise this here to check whether maybe there's a wider issue that needs looking at?


Attachments (1)

template-docs.diff (9.2 KB) - added by Adam Vandenberg 10 years ago.

Download all attachments as: .zip

Change History (5)

comment:1 Changed 11 years ago by Russell Keith-Magee

Triage Stage: UnreviewedAccepted

The answer is a little of column A, and a little of column B.

Django's docs were originally just raw Restructured Text. Just prior to v1.0, we made the conversion to Sphinx. However, as you can imagine, there was a lot of conversion to do. On top of that, the old ReST docs didn't have indexes, contents pages, etc. As a result, there are several problems hanging around. To take your class reference issue as an example:

  • There are old-style ReST references to classes, rather than sphinx-annotated :class: references
  • There are missing index entries (i.e., putting the anchor in the docs where the class is defined).
  • There is documentation that is just plain missing for some classes.

There is a TODO listing work that needs to be done on the docs.

This problem isn't a simple as a single ticket - There are lots of individual issues to be resolved, and through a process of gradual improvement, many patches will be required. I'll leave this ticket open as a placeholder for the specific "missing class references" problem. Please open new tickets (with patches) if you want to work on another class of problem.

comment:2 Changed 10 years ago by Adam Vandenberg

Has patch: set
Summary: Some classes missing in documentationSome classes missing in documentation (Template docs)
Version: 1.0SVN

I've worked up a patch with a few doc improvements and tweaks; it doesn't address everything but perhaps it is enough to resolve this issue for now.

Changed 10 years ago by Adam Vandenberg

Attachment: template-docs.diff added

comment:3 Changed 10 years ago by Tim Graham

Resolution: fixed
Status: newclosed

(In [14744]) Fixed #11152 - Add some classes to the template docs. Thanks adamv for the patch.

comment:4 Changed 10 years ago by Tim Graham

(In [14745]) [1.2.X] Fixed #11152 - Add some classes to the template docs. Thanks adamv for the patch.

Backport of r14744 from trunk.

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