Opened 14 years ago

Closed 13 years ago

Last modified 12 years ago

#13628 closed (fixed)

Documentation should discourage the usage of doctests

Reported by: Dougal Matthews Owned by: Dougal Matthews
Component: Documentation Version: dev
Severity: 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

At the moment the documentation described both doctest and unit tests without giving the reader and guidance to one or the other. It is generally agree'd that unit tests are a better choice. I have added a patch with a small patch that adds a note to reflect this.

However, I'm not sure if this reflects a bigger problem - should unit tests be described first and docetests second so that the reader doesn't read through that section only to find out its not recommended? Or should the note be added to the top and further emphasised?

Attachments (3)

unitdest-warning.diff (797 bytes ) - added by Dougal Matthews 14 years ago.
doctest-warning.diff (795 bytes ) - added by Dougal Matthews 14 years ago.
13628.diff (11.0 KB ) - added by Tim Graham 13 years ago.
reorg of testing.txt as per Luke's recommendation

Download all attachments as: .zip

Change History (14)

by Dougal Matthews, 14 years ago

Attachment: unitdest-warning.diff added

comment:1 by Dougal Matthews, 14 years ago

Has patch: set

comment:2 by Adam Nelson, 14 years ago

Patch needs improvement: set

If a committer approves this, the grammar needs to be fixed in the patch.

comment:3 by Jannis Leidel, 14 years ago

Triage Stage: UnreviewedAccepted

comment:4 by Dougal Matthews, 14 years ago

Owner: changed from nobody to Dougal Matthews
Status: newassigned

by Dougal Matthews, 14 years ago

Attachment: doctest-warning.diff added

comment:5 by Dougal Matthews, 14 years ago

Patch needs improvement: unset

Added a new patch that makes more sense. Apologies for the previous rush sloppy version.

comment:6 by Tim Graham, 14 years ago

Triage Stage: AcceptedReady for checkin

comment:7 by Luke Plant, 14 years ago

Patch needs improvement: set
Triage Stage: Ready for checkinAccepted

I'm not happy with the patch as it is. We still have other statements on that page that suggest that both frameworks are equally valid choices. And we already have a section entitled "which should I use" (which is the area where it is logical to put this change), and that section is actually fairly positive towards doctests, calling them Pythonic, implying that they are for experienced developers, when actually the experience of most Django developers leads us away from them for serious testing. The problem is that while they are good for quick, simple testing, and good for some simple example code, they are not very good if you want to produce either high quality, comprehensive tests or high quality documentation.

So, a bit of a rework of that page is in order if we want to avoid contradicting ourselves:

  • switching to put unittests first like you suggest (which requires a bit of rework of the sections themselves)
  • reworking the sentence that says "You can choose the test framework you like, depending on which syntax you prefer" to be less ambivalent (maybe just remove it)
  • and modifying the section "which should I use" to emphasise these things about the limitations of doctests and when they are appropriate.

Thanks

by Tim Graham, 13 years ago

Attachment: 13628.diff added

reorg of testing.txt as per Luke's recommendation

comment:8 by Tim Graham, 13 years ago

Patch needs improvement: unset

comment:9 by Tim Graham, 13 years ago

Resolution: fixed
Status: assignedclosed

(In [15227]) Fixed #13628 - Discourage the use of doctests; thanks d0ugal for the suggestion.

comment:10 by Tim Graham, 13 years ago

(In [15228]) [1.2.X] Fixed #13628 - Discourage the use of doctests; thanks d0ugal for the suggestion.

Backport of r15227 from trunk.

comment:11 by Jacob, 12 years ago

milestone: 1.3

Milestone 1.3 deleted

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