#13628: Documentation should discourage the usage of doctests
------------------------------------+---------------------------------------
Reporter: d0ugal | Owner: d0ugal
Status: assigned | Milestone: 1.3
Component: Documentation | Version: SVN
Resolution: | Keywords:
Stage: Accepted | Has_patch: 1
Needs_docs: 0 | Needs_tests: 0
Needs_better_patch: 1 |
------------------------------------+---------------------------------------
Changes (by lukeplant):
* needs_better_patch: 0 => 1
* stage: Ready for checkin => Accepted
Comment:
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
--
Ticket URL: <http://code.djangoproject.com/ticket/13628#comment:7>
Django <http://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
--
You received this message because you are subscribed to the Google Groups
"Django updates" group.
To post to this group, send email to [email protected].
To unsubscribe from this group, send email to
[email protected].
For more options, visit this group at
http://groups.google.com/group/django-updates?hl=en.
