Opened 5 years ago

Closed 5 years ago

Last modified 4 years ago

#13628 closed (fixed)

Documentation should discourage the usage of doctests

Reported by: d0ugal Owned by: d0ugal
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 d0ugal 5 years ago.
doctest-warning.diff (795 bytes) - added by d0ugal 5 years ago.
13628.diff (11.0 KB) - added by timo 5 years ago.
reorg of testing.txt as per Luke's recommendation

Download all attachments as: .zip

Change History (14)

Changed 5 years ago by d0ugal

comment:1 Changed 5 years ago by d0ugal

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

comment:2 Changed 5 years ago by adamnelson

  • Patch needs improvement set

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

comment:3 Changed 5 years ago by jezdez

  • Triage Stage changed from Unreviewed to Accepted

comment:4 Changed 5 years ago by d0ugal

  • Owner changed from nobody to d0ugal
  • Status changed from new to assigned

Changed 5 years ago by d0ugal

comment:5 Changed 5 years ago by d0ugal

  • Patch needs improvement unset

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

comment:6 Changed 5 years ago by timo

  • Triage Stage changed from Accepted to Ready for checkin

comment:7 Changed 5 years ago by lukeplant

  • Patch needs improvement set
  • Triage Stage changed from Ready for checkin to Accepted

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

reorg of testing.txt as per Luke's recommendation

comment:8 Changed 5 years ago by timo

  • Patch needs improvement unset

comment:9 Changed 5 years ago by timo

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

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

comment:10 Changed 5 years ago by timo

(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 4 years ago by jacob

  • milestone 1.3 deleted

Milestone 1.3 deleted

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