Some classes missing in documentation (Template docs)

[ben]

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

​http://docs.djangoproject.com/en/dev/ref/templates/api/#rendering-a-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?

Ben

[Russell Keith-Magee]

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.

[Adam Vandenberg]

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.

[Tim Graham]

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

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