Jim DeLaHunt added the comment: Marco, thank you for the suggestion of a howto. That is a good idea.
In parallel, I was thinking of some howto content that I would like to see documented. • How to decide what to test with doctests and what with unittests. I have a feeling that the sweet spot of doctests is functionality which you can invoke in one line, and which produces one line of output which you can match against a reference string. If it takes many lines to set up, or invoke, or checking for correctness is more than a test for string equality, then maybe unittest is a better tool. • An effective way to write doctests. I suspect that some people write doctests by exercising the functionality in Python's interactive mode, then copy and paste the transcript from that session to the doctests. I don't do it that way, I author in the docstring. Maybe I'm not doing it the best way. • How to author doctests so that they both prove the module correct, and provide clear and readable documentation. I imagine some effective tests for edge cases and error conditions are important to have, but are not readable documentation. Maybe such tests belong in a unittest framework instead of as doctests. • How to run doctests from a unittest harness (your earlier note about the unittest API would be a part of this). A problem for me is that I think I don't have the experience and wisdom to give good advice in these areas. I would be happy to start such a howto, and to accept feedback, and to edit it into good prose. I would need wiser people to contribute good ideas for the howto. Also, Marco, thank you for being willing to review a patch. That is helpful. My next step is to check out the documentation source, to be in a position to make a patch. ---------- _______________________________________ Python tracker <rep...@bugs.python.org> <http://bugs.python.org/issue29428> _______________________________________ _______________________________________________ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
