Documentation should discourage the usage of doctests

[Dougal Matthews]

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?

[Adam Nelson]

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

[Dougal Matthews]

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

[Luke Plant]

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

[Tim Graham]

reorg of testing.txt as per Luke's recommendation

[Tim Graham]

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

[Tim Graham]

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

Backport of r15227 from trunk.

[Jacob]

Milestone 1.3 deleted