RetroSearch Browse

Fri Aug 6 14:54:45 CEST 2004 · https://mail.python.org/pipermail/python-dev/2004-August/047094.html

Tim Peters wrote:
> better support for writing "whole file" doctests (tutorial narratives
> liberally illustrated with Python examples -- Zope3 is finding these very
> helpful); and documenting all the additions that snuck into Python 2.3.

I noticed that the "whole file doctests" item didn't make it to the 
DoctestIdeas page.  I was looking for more details about that.

I've found that for tutorial narratives, I really don't want to bother 
with expected output.  For complex software, the output may not always 
be the same anyway.  Also, it's not fun to manipulate input code that 
has prompts and is within a multi-line string.  Syntax highlighting is 
not available, for one thing.

I've made my own tutorial generator.  Given this input script:

     ## Double hash comments treated as meta comments and not output to
     ## the tutorial.

     """
     Triple-quote comments that start in the first column are treated as
     tutorial text.

     First we'll import some modules:
     """
     import os

     """
     Some code follows.  In addition to hash comments, and triple-quote
     comments not starting in the first column are preserved.  Note that
     code blocks such as functions must end with a blank line, just as
     is done in the interactive interpreter.
     """

     def foo():
         """foo description here"""
         print 'hello'  # be friendly

     #my_path = 'foo/bar'
     my_path = os.path.join('foo', 'bar')
     my_path
     foo()

the output is:

     Triple-quote comments that start in the first column are treated as
     tutorial text.

     First we'll import some modules:

         >>> import os

     Some code follows.  In addition to hash comments, and triple-quote
     comments not starting in the first column are preserved.  Note that
     code blocks such as functions must end with a blank line, just as
     is done in the interactive interpreter.

         >>> def foo():
         ...     """foo description here"""
         ...     print 'hello'  # be friendly
         ...
         >>> #my_path = 'foo/bar'
         >>> my_path = os.path.join('foo', 'bar')
         >>> my_path
         'foo/bar'
         >>> foo()
         hello

-John

-- 
http://giftfile.org/  ::  giftfile project

Home - News ( United States | United Kingdom | Italy | Germany ) - Football scores

Showing content from https://mail.python.org/pipermail/python-dev/2004-August/047094.html below:

[Python-Dev] Would like to add Edward Loper as a Python developer