Opened 6 years ago

Closed 5 years ago

Last modified 5 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: UI/UX:

Description

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

Attachments (1)

template-docs.diff (9.2 KB) - added by adamv 5 years ago.

Download all attachments as: .zip

Change History (5)

comment:1 Changed 6 years ago by russellm

  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset
  • Triage Stage changed from Unreviewed to Accepted

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

  • Has patch set
  • Summary changed from Some classes missing in documentation to Some classes missing in documentation (Template docs)
  • Version changed from 1.0 to SVN

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

comment:3 Changed 5 years ago by timo

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

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

comment:4 Changed 5 years ago by timo

(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