[Patches] [ python-Patches-732394 ] Docs for test package

[SourceForge.net]

Patches item #732394, was opened at 2003-05-04 18:09
Message generated for change (Comment added) made by rhettinger
You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=305470&aid=732394&group_id=5470

Category: Documentation
Group: Python 2.3
Status: Open
Resolution: None
Priority: 5
Submitted By: Brett Cannon (bcannon)
Assigned to: Nobody/Anonymous (nobody)
Summary: Docs for test package

Initial Comment:
Here is an attempt to document the test package.  I tried to explain 
what the package is for, document test_support (but only things 
relevant to unittest tests; no need to push older-style tests), how to 
write a test for the package, and how to use regrtest.py (roughly).

The only thing I am not sure on is what the preferred way to execute 
tests is anymore; is it run_suite or run_unittest from test_support?  
Now that run_unittest takes in *classes should we be pushing that 
since the code is shorter and less error-prone?

----------------------------------------------------------------------

>Comment By: Raymond Hettinger (rhettinger)
Date: 2003-05-06 01:46

Message:
Logged In: YES 
user_id=80475

Well, it does have an air of near perfection ;)  The content, 
accuracy, and completeness are ten times more 
important than the form :-)

Most of the stuff is just a one element change.  The 
abbreviations are just a style manual thing.  When you 
write your second set of docs almost none of this will 
come up.  

Things like section markers and seealso's are pretty easy.  
The trick is to write docs by pasting in snippet's from other 
docs.  I always find the nearest match (in form, not 
content) and keep it open while writing the docs.

The attached script may help.  It catches the kind of TeX 
errors that I tend to make.  BTW, the hard knocks 
document may have understated this one a bit.

----------------------------------------------------------------------

Comment By: Brett Cannon (bcannon)
Date: 2003-05-06 00:43

Message:
Logged In: YES 
user_id=357491

Ah nuts, Raymond.  You were supposed to say it was perfect.  =)

OK, I will make the fixes and clean up the text to be more terse and sterile.  
So this is why people hate writing docs...

----------------------------------------------------------------------

Comment By: Raymond Hettinger (rhettinger)
Date: 2003-05-05 18:31

Message:
Logged In: YES 
user_id=80475

The \section title should indicate that the regression tests 
are for python itself.

Add a seealso note referencing unittest and doctest.

On line 78, \dict{sys.modules} should be \module
{sys.modules}.

On line 123, remove the exclamation point and explain the 
guideline rationale (docstrings get printed out, but 
comments don't).

On line 194, add a closing parenthesis.

On line 226, \Windows{} should be Windows.

In either the guidelines section or the example section, 
show how common code can be factored out through 
subclassing (this question comes-up alot):

   class TestFuncAcceptsSequences(unittest.TestCase):
       self.func = mySuperWhammyFunction
       def test_func(self):
           self.func (self.arg)
   class AcceptLists(TestFuncAcceptsSequences):
       arg = [1,2,3]
   class AcceptStrings(TestFuncAcceptsSequences):
       arg = 'abc'
   class AcceptTuples(TestFuncAcceptsSequences):
       arg = (1,2,3)


Everywhere.  Do not use abbreviations like e.g., i.e. and 
etc.  They do not transate well and Fred will come in 
behind you and remove them all.

Change the voice to not speak directly to the reader.  None 
of this:  "you will most likely not use these modules 
directly".  Instead try:  "Except for test_support.py, most of 
these modules are not needed by user code".

New tests do not *have to be* in unittest format.  Instead, 
mention that the unittest format is more flexible and 
easier to extend for future maintainers.

At the end, refer readers to Kent Beck's Test-Driven 
Development for more guidelines.

Try to tighten-up the sentence structure to be much more 
terse and concrete.  Avoid vague "recommended" 
or "prohibited" talk, instead giving fact based advantages 
and disadvantages.  

Consider a three or four part grouping:
* First, collect all of the prose into one intro section.
* Put the function/method description one section.
* Put the examples/boilerplate in another.
* Final collect the guidelines in a separate section.
See libsets.tex and libitertools.tex to see how it's done and 
what it looks like.


----------------------------------------------------------------------

Comment By: Raymond Hettinger (rhettinger)
Date: 2003-05-05 17:33

Message:
Logged In: YES 
user_id=80475

Yes, run_unittest(*classes) is the most general and 
requires the least boilerplate.

Will read through your docs tonight.  Thanks for
the effort to take this beyond (read the code to
figure out what it does).

----------------------------------------------------------------------

You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=305470&aid=732394&group_id=5470