Opened 6 years ago

Closed 6 years ago

Last modified 5 years ago

#13628 closed (fixed)

Documentation should discourage the usage of doctests

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

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 6 years ago.
doctest-warning.diff (795 bytes) - added by Dougal Matthews 6 years ago.
13628.diff (11.0 KB) - added by Tim Graham 6 years ago.
reorg of testing.txt as per Luke's recommendation

Download all attachments as: .zip

Change History (14)

Changed 6 years ago by Dougal Matthews

Attachment: unitdest-warning.diff added

comment:1 Changed 6 years ago by Dougal Matthews

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

comment:2 Changed 6 years ago by Adam Nelson

Patch needs improvement: set

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

comment:3 Changed 6 years ago by Jannis Leidel

Triage Stage: UnreviewedAccepted

comment:4 Changed 6 years ago by Dougal Matthews

Owner: changed from nobody to Dougal Matthews
Status: newassigned

Changed 6 years ago by Dougal Matthews

Attachment: doctest-warning.diff added

comment:5 Changed 6 years ago by Dougal Matthews

Patch needs improvement: unset

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

comment:6 Changed 6 years ago by Tim Graham

Triage Stage: AcceptedReady for checkin

comment:7 Changed 6 years ago by Luke Plant

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

Changed 6 years ago by Tim Graham

Attachment: 13628.diff added

reorg of testing.txt as per Luke's recommendation

comment:8 Changed 6 years ago by Tim Graham

Patch needs improvement: unset

comment:9 Changed 6 years ago by Tim Graham

Resolution: fixed
Status: assignedclosed

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

comment:10 Changed 6 years ago by Tim Graham

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

Backport of r15227 from trunk.

comment:11 Changed 5 years ago by Jacob

milestone: 1.3

Milestone 1.3 deleted

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