Code

Opened 2 years ago

Closed 20 months ago

#17378 closed New feature (fixed)

add "squashed" index of CBV reference documentation

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

Description

The current CBV reference documentation is organized by mixin, then by view classes documenting attributes and methods where they are defined.

This is a valid approach for documenting the collection of mixins as a "toolkit" for building your own class-based views, but is problematic to use as someone just using the resulting generic class-based views. Understanding just the use of the generic views requires jumping all around the reference documentation by looking at what mixins are used.

Originally I looked into duplicating the reference documentation under two different organizations by updating docstrings and using inspect.getdoc - however the Django documentation is usually more than what is in a docstring, and I didn't want to inject too much doc building machinery. So the compromise was to use a script to traverse the class MRO for each view and generate an alternative index, linking to the current documentation.

this is related to 16807

Attachments (1)

17378.diff (34.8 KB) - added by timo 20 months ago.
Fixed a couple typos in Preston's original pull request and updated formatting

Download all attachments as: .zip

Change History (5)

comment:1 Changed 2 years ago by ptone

  • Has patch set
  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset

comment:2 Changed 2 years ago by Alex

  • Triage Stage changed from Unreviewed to Accepted

comment:3 Changed 23 months ago by charlie@…

I have written something like this at http://ccbv.co.uk/ and would really like to get involved with getting something like this into the official docs.

Changed 20 months ago by timo

Fixed a couple typos in Preston's original pull request and updated formatting

comment:4 Changed 20 months ago by Tim Graham <timograham@…>

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

In [5faadea439a405ecd80ec06c0d6a769e47ebeec2]:

Fixed #17378 - Added a flattened index for class-based views.

Thanks Preston Holmes for the patch.

Add Comment

Modify Ticket

Change Properties
<Author field>
Action
as closed
as The resolution will be set. Next status will be 'closed'
The resolution will be deleted. Next status will be 'new'
Author


E-mail address and user name can be saved in the Preferences.

 
Note: See TracTickets for help on using tickets.