From gward@python.net  Sat May  3 20:21:31 2003
From: gward@python.net (Greg Ward)
Date: Sat, 3 May 2003 15:21:31 -0400
Subject: [Doc-SIG] optparse docs need proofreading
Message-ID: <20030503192131.GA4689@cthulhu.gerg.ca>

So you're sitting around, wondering what to do with your weekend, and
worrying that the Python 2.3 documentation is not perfect yet.  Well,
you could proofread the documentation for optparse (currently section
6.20 of the "lib" manual), which was converted wholesale from
reStructuredText to LaTeX, and still bears some scars.  Both the
DVI/PS/PDF output and HTML bear close examination.

I'm working on it now, but will undoubtedly miss stuff, so feel free to
email any glitches you notice in the latest CVS version to me.

        Greg
-- 
Greg Ward <gward@python.net>                         http://www.gerg.ca/


From barry@python.org  Fri May 16 16:44:44 2003
From: barry@python.org (Barry Warsaw)
Date: 16 May 2003 11:44:44 -0400
Subject: [Doc-SIG] Re: [Python-Dev] [development doc updates]
In-Reply-To: <20030516153518.68B1B18EC13@grendel.zope.com>
References: <20030516153518.68B1B18EC13@grendel.zope.com>
Message-ID: <1053099884.1849.49.camel@barry>

On Fri, 2003-05-16 at 11:35, Fred L. Drake wrote:
> The development version of the documentation has been updated:
> 
>     http://www.python.org/dev/doc/devel/
> 
> Various updates, including Jim Fulton's efforts on updating the Extending &
> Embedding manual.

I think this one's gonna make my Python quotes file:

"So, if you want to define a new object type, you need to create a new
type object."

:)
-Barry




From fdrake@acm.org  Fri May 16 17:00:08 2003
From: fdrake@acm.org (Fred L. Drake, Jr.)
Date: Fri, 16 May 2003 12:00:08 -0400
Subject: [Doc-SIG] Re: [Python-Dev] [development doc updates]
In-Reply-To: <1053099884.1849.49.camel@barry>
References: <20030516153518.68B1B18EC13@grendel.zope.com>
 <1053099884.1849.49.camel@barry>
Message-ID: <16069.2824.324295.354588@grendel.zope.com>

Barry Warsaw writes:
 > I think this one's gonna make my Python quotes file:
 > 
 > "So, if you want to define a new object type, you need to create a new
 > type object."

Yeah; I guess I should find a little time to read through this before
too long.  ;-)


  -Fred

-- 
Fred L. Drake, Jr.  <fdrake at acm.org>
PythonLabs at Zope Corporation


From 25jy0v309a@aol.com  Mon May 19 07:42:09 2003
From: 25jy0v309a@aol.com (Rachael Nicholson)
Date: Mon, 19 May 03 06:42:09 GMT
Subject: [Doc-SIG] Free Cable, save some extra money. qsunbcdmael rc ew jk
Message-ID: <g2-4-e-yi657-$6$v$h95j-tp4@3yqff.8g5m>

This is a multi-part message in MIME format.

--.D97E9F7_38FEBB0BD
Content-Type: text/plain
Content-Transfer-Encoding: quoted-printable

FREE CABLE PPV's FOR LIFE - Only $45 one-time fee !

Think about the $1000's you will save in Free Tv for only $45.

* Free Adult Movies
* Free PPV Movies
* Free Sporting Events like Wrestling & Boxing
* ETC

*Bonus: Get a Free cell/cordless Phone Shield/Booster with your order! 
This reduces the chances of cancer when using your phone & increases 
your signal quality drastically. A $20 value FREE with order.

ACT NOW !!!


Click Here as offer expires soon-->  
http://www.a6zing29.com/xcart/customer/product.php?productid=3D16144&partn=
er=3Daffil10&r=3Dfreetv




















""OPT-OUT"" system in compliance with state laws. If you wish to 
"OPT-OUT" from this mailing as well as the lists of thousands of other ema=
il 
providers please visit http://www.a6zing29.com/1/

2va loen ghztodru  wjgdnzviiagonpflpll hnpajt
--.D97E9F7_38FEBB0BD--



From anthony@interlink.com.au  Mon May 19 05:47:14 2003
From: anthony@interlink.com.au (Anthony Baxter)
Date: Mon, 19 May 2003 14:47:14 +1000
Subject: [Doc-SIG] why no macros for DOS/Windows and MacOS?
Message-ID: <200305190447.h4J4lF317659@localhost.localdomain>

We have a standard macro for Posix, for Unix, but none for DOS/Windows or
for MacOS. Is this deliberate? Should it be added?




From fdrake@acm.org  Mon May 19 07:26:41 2003
From: fdrake@acm.org (Fred L. Drake, Jr.)
Date: Mon, 19 May 2003 02:26:41 -0400
Subject: [Doc-SIG] why no macros for DOS/Windows and MacOS?
In-Reply-To: <200305190447.h4J4lF317659@localhost.localdomain>
References: <200305190447.h4J4lF317659@localhost.localdomain>
Message-ID: <16072.31009.16197.280939@grendel.zope.com>

Anthony Baxter writes:
 > We have a standard macro for Posix, for Unix, but none for DOS/Windows or
 > for MacOS. Is this deliberate? Should it be added?

Anthony,

The POSIX and Unix macros are quite old (along with the ASCII macro),
being added before I wrested maintenace of the docs from our BDFL.
Various discussions with him lead me to believe that he's not overly
fond of them, and would rather they not exist.  I don't really agree
with him on this point, and have resisted removing them, but it's more
of a vague feeling that they're reasonable.

On the other hand, of course, *adding* new macros for simple
substitutions that seem unlikely to ever change is a hard case to
make, especially given that so many new document fragments that get
added don't initially have these marked.

The typical use case in technical documentation for this kind of
markup is product names; you can define a name to mean "this product",
and then rename the product independently (somewhat) of the using the
references by changing the macro definition.  So, it's not a macro for
Windows or Mac OS that should be defined, but for \Python.  Just try
and get that past \Guido.  ;-)

Conceivably, we could define macros for Windows and Mac OS for
consistency (\Guido{} wouldn't be happy), and at least for Mac OS we
could say it's for consistent treatment of the embedded space.  But
this is at least somewhat contrived.  I'd be happier if we had a
concrete requirement to "hook into" references, whether for
typesetting (as we do for \UNIX), indexing (unlikely to be helpful),
or for some other purpose.

What did you have in mind?


  -Fred

-- 
Fred L. Drake, Jr.  <fdrake at acm.org>
PythonLabs at Zope Corporation


From pa8496id4w2@hotmail.com  Tue May 20 22:03:30 2003
From: pa8496id4w2@hotmail.com (Sammie Porter)
Date: Tue, 20 May 03 21:03:30 GMT
Subject: [Doc-SIG] Re: Mortgage Interest Rates Drop Again bfpvbczfjhzdf
Message-ID: <a65y8$e$86$n8e@8vpwlm1l>

This is a multi-part message in MIME format.

--1_34FB3A42E4_EEC80AC.FD.
Content-Type: text/plain
Content-Transfer-Encoding: quoted-printable

FREE MORTGAGE QUOTE & BEST POSSIBLE RATES !
-------------------------------------------

Home Improvement
Refinance 
Second Mortgage 
Home Equity Loans
and More

Even with less than perfect or NO credit!

You will qualify for the best possible rate. Do NOT miss the chance to 
refinance at record low rates, so act now...

http://www.wuyi-shop.com/3/index.asp?RefID=3D383102 

















remove
http://gethelpu.com/Auto/index.htm





f wkdtmy ncvnkfo
iofg
--1_34FB3A42E4_EEC80AC.FD.--



From fdrake@acm.org  Thu May 22 15:09:25 2003
From: fdrake@acm.org (Fred L. Drake, Jr.)
Date: Thu, 22 May 2003 10:09:25 -0400
Subject: [Doc-SIG] Preparing docs for Python 2.2.3
Message-ID: <16076.55829.218985.714016@grendel.zope.com>

I'll be preparing the Python docs for the 2.2.3 release today.  If
there are any fixes for 2.2.3 that absolutely *must* go in, we need to
get them in over the next four hours.

I don't expect to have any sort of Internet access from Friday
(tomorrow) through next Tuesday, so the docs really need to be
finished today.


  -Fred

-- 
Fred L. Drake, Jr.  <fdrake at acm.org>
PythonLabs at Zope Corporation


From magnus@thinkware.se  Sat May 24 11:53:54 2003
From: magnus@thinkware.se (Magnus =?iso-8859-1?Q?Lyck=E5?=)
Date: Sat, 24 May 2003 12:53:54 +0200
Subject: [Doc-SIG] Re: [Tutor] Documentation concerns.
In-Reply-To: <000301c321c2$0332f8b0$6401a8c0@xp>
References: <5.2.1.1.0.20030523022201.01f05c00@www.thinkware.se>
 <013801c32040$9fb80960$6401a8c0@xp>
 <5.2.0.9.0.20030520062251.027be6e8@66.28.54.253>
 <5.2.0.9.0.20030521112455.0387da20@66.28.54.253>
 <5.2.1.1.0.20030523022201.01f05c00@www.thinkware.se>
 <5.2.1.1.0.20030523223300.01efca58@www.thinkware.se>
 <m3znlduv1p.fsf@ieee.org>
Message-ID: <5.2.1.1.0.20030524103225.01edd0a8@www.thinkware.se>

There is currently a discussion about the Python documentation in
the Tutor mailing list.

One issue in particular is whether the main documentation for
the module should be in the module itself, rather than in a
separate document.

What are the attitudes about this today? In PEP 287 it says:

"10. Will the docstrings in the Python standard library modules
      be converted to reStructuredText?

No. Python's library reference documentation is maintained separately
from the source. Docstrings in the Python standard library should not
try to duplicate the library reference documentation. The current
policy for docstrings in the Python standard library is that they
should be no more than concise hints, simple and markup-free (although
many do contain ad-hoc implicit markup)."

Is this still gospel? Any further thoughts around this?


--
Magnus Lycka (It's really Lyck&aring;), magnus@thinkware.se
Thinkware AB, Sweden, www.thinkware.se
I code Python ~ The shortest path from thought to working program 



From guido@python.org  Sat May 24 19:03:01 2003
From: guido@python.org (Guido van Rossum)
Date: Sat, 24 May 2003 14:03:01 -0400
Subject: [Doc-SIG] Re: [Tutor] Documentation concerns.
In-Reply-To: "Your message of Sat, 24 May 2003 12:53:54 +0200."
 <5.2.1.1.0.20030524103225.01edd0a8@www.thinkware.se>
References: <5.2.1.1.0.20030523022201.01f05c00@www.thinkware.se>
 <013801c32040$9fb80960$6401a8c0@xp>
 <5.2.0.9.0.20030520062251.027be6e8@66.28.54.253>
 <5.2.0.9.0.20030521112455.0387da20@66.28.54.253>
 <5.2.1.1.0.20030523022201.01f05c00@www.thinkware.se>
 <5.2.1.1.0.20030523223300.01efca58@www.thinkware.se> <m3znlduv1p.fsf@ieee.org>
 <5.2.1.1.0.20030524103225.01edd0a8@www.thinkware.se>
Message-ID: <200305241803.h4OI31w27894@pcp02138704pcs.reston01.va.comcast.net>

> There is currently a discussion about the Python documentation in
> the Tutor mailing list.
> 
> One issue in particular is whether the main documentation for
> the module should be in the module itself, rather than in a
> separate document.

This is a contentious issue that every project has to decide for
itself.

I personally think that documentation external to the code, while it
takes more time to create and maintain, can also be of better quality
than documentation maintained as part of the code.  I like to see
docstrings that serve as comments to the code and at the same time
serve as concise reference docs.

But every project has its own constraints, and I can certainly
understand why some projects prefer to have the full user
documentation as docstrings.  I expect that such projects will still
require some external documentation, e.g. a separate tutorial.

> What are the attitudes about this today? In PEP 287 it says:
> 
> "10. Will the docstrings in the Python standard library modules
>       be converted to reStructuredText?
> 
> No. Python's library reference documentation is maintained separately
> from the source. Docstrings in the Python standard library should not
> try to duplicate the library reference documentation. The current
> policy for docstrings in the Python standard library is that they
> should be no more than concise hints, simple and markup-free (although
> many do contain ad-hoc implicit markup)."
> 
> Is this still gospel? Any further thoughts around this?

This is still gospel for the Python standard library.

--Guido van Rossum (home page: http://www.python.org/~guido/)



From ianb@colorstudy.com  Sat May 24 20:36:18 2003
From: ianb@colorstudy.com (Ian Bicking)
Date: 24 May 2003 14:36:18 -0500
Subject: [Doc-SIG] Re: [Tutor] Documentation concerns.
In-Reply-To: <5.2.1.1.0.20030524103225.01edd0a8@www.thinkware.se>
References: <5.2.1.1.0.20030523022201.01f05c00@www.thinkware.se>
 <013801c32040$9fb80960$6401a8c0@xp>
 <5.2.0.9.0.20030520062251.027be6e8@66.28.54.253>
 <5.2.0.9.0.20030521112455.0387da20@66.28.54.253>
 <5.2.1.1.0.20030523022201.01f05c00@www.thinkware.se>
 <5.2.1.1.0.20030523223300.01efca58@www.thinkware.se>
 <m3znlduv1p.fsf@ieee.org>
 <5.2.1.1.0.20030524103225.01edd0a8@www.thinkware.se>
Message-ID: <1053804978.1167.49.camel@lothlorien>

On Sat, 2003-05-24 at 05:53, Magnus Lyck=E5 wrote:
> One issue in particular is whether the main documentation for
> the module should be in the module itself, rather than in a
> separate document.

One issue I see with moving the documentation into the code, is that we
don't have any system that can represent the kind of documentation from
the standard library as docstrings.  Typically documentation created
from docstrings is highly (overly) structured, and does not allow items
to be introduced in an order different from the code, or presented with
a different structure than the code, plus there is no place for
narrative that is not connected with a function or class.

  Ian




From magnus@thinkware.se  Sat May 24 22:05:51 2003
From: magnus@thinkware.se (Magnus =?iso-8859-1?Q?Lyck=E5?=)
Date: Sat, 24 May 2003 23:05:51 +0200
Subject: [Doc-SIG] Re: [Tutor] Documentation concerns.
In-Reply-To: <1053804978.1167.49.camel@lothlorien>
References: <5.2.1.1.0.20030524103225.01edd0a8@www.thinkware.se>
 <5.2.1.1.0.20030523022201.01f05c00@www.thinkware.se>
 <013801c32040$9fb80960$6401a8c0@xp>
 <5.2.0.9.0.20030520062251.027be6e8@66.28.54.253>
 <5.2.0.9.0.20030521112455.0387da20@66.28.54.253>
 <5.2.1.1.0.20030523022201.01f05c00@www.thinkware.se>
 <5.2.1.1.0.20030523223300.01efca58@www.thinkware.se>
 <m3znlduv1p.fsf@ieee.org>
 <5.2.1.1.0.20030524103225.01edd0a8@www.thinkware.se>
Message-ID: <5.2.1.1.0.20030524225458.01ec9430@www.thinkware.se>

At 14:36 2003-05-24 -0500, Ian Bicking wrote:
>One issue I see with moving the documentation into the code, is that we
>don't have any system that can represent the kind of documentation from
>the standard library as docstrings.  Typically documentation created
>from docstrings is highly (overly) structured, and does not allow items
>to be introduced in an order different from the code, or presented with
>a different structure than the code, plus there is no place for
>narrative that is not connected with a function or class.

You can always put a big blurb in the beginning of the module, but I
agree, and I argued the same in python-tutor. You can't expect that
the best structure for the implementation would be the best structure
to explain how to work with the software.

On the other hand, even if it takes some restructuring of the extracted
data, it seems that the docstrings for methods and functions should
typically contain the same information as we would have in the
corresponding part of the documentation. It seems very redundant to
write that twice.

Another issue is that it's great if documention examples are written
as doctest strings and run as part of a test suite. In that way, we
can at least verify that that part of the documentation is synchronized
with the implementation.

Maybe the best solution is some kind of mix.


--
Magnus Lycka (It's really Lyck&aring;), magnus@thinkware.se
Thinkware AB, Sweden, www.thinkware.se
I code Python ~ The shortest path from thought to working program 



From goodger@python.org  Sat May 24 22:16:06 2003
From: goodger@python.org (David Goodger)
Date: Sat, 24 May 2003 17:16:06 -0400
Subject: [Doc-SIG] Updates to Docutils
Message-ID: <3ECFE116.5040306@python.org>

A burst of creativity over the last few days has resulted in a slew of
checkins.  The snapshot has all the latest code:

     http://docutils.sf.net/docutils-snapshot.tgz

New doctree elements implemented: "rubric", "admonition", and
"attribution" (part of block quotes; see
<http://docutils.sf.net/spec/rst/reStructuredText.html#block-quotes>).

New directives implemented: "admonition", "rubric", "epigraph",
"highlights", "unicode" and "class".  Also added "class" options to
"topic", "sidebar", "line-block", "parsed-literal", "contents", and
"image"; and "figclass" to "figure".  See
<http://docutils.sf.net/spec/rst/directives.html>.  The change to
"line-block" and "parsed-literal" may cause problems; a blank line is
now required before the directive content.

The HTML Writer and default.css stylesheet have been updated to
support all of this.

Please give the latest code a try and report any problems you
encounter.  Enjoy!

-- 
David Goodger    http://starship.python.net/~goodger

Programmer/sysadmin for hire: http://starship.python.net/~goodger/cv



From godoy@metalab.unc.edu  Sun May 25 20:53:35 2003
From: godoy@metalab.unc.edu (Jorge Godoy)
Date: Sun, 25 May 2003 16:53:35 -0300
Subject: [Doc-SIG] Re: [Tutor] Documentation concerns.
In-Reply-To: <200305241803.h4OI31w27894@pcp02138704pcs.reston01.va.comcast.net> (Guido
 van Rossum's message of "Sat, 24 May 2003 14:03:01 -0400")
References: <5.2.1.1.0.20030523022201.01f05c00@www.thinkware.se>
 <013801c32040$9fb80960$6401a8c0@xp>
 <5.2.0.9.0.20030520062251.027be6e8@66.28.54.253>
 <5.2.0.9.0.20030521112455.0387da20@66.28.54.253>
 <5.2.1.1.0.20030523022201.01f05c00@www.thinkware.se>
 <5.2.1.1.0.20030523223300.01efca58@www.thinkware.se>
 <m3znlduv1p.fsf@ieee.org>
 <5.2.1.1.0.20030524103225.01edd0a8@www.thinkware.se>
 <200305241803.h4OI31w27894@pcp02138704pcs.reston01.va.comcast.net>
Message-ID: <m3fzn2ref4.fsf@ieee.org>

Guido van Rossum <guido@python.org> writes:

> But every project has its own constraints, and I can certainly
> understand why some projects prefer to have the full user
> documentation as docstrings.  I expect that such projects will still
> require some external documentation, e.g. a separate tutorial.

I was one of the people who suggested the documentation within the
module. 

Let me try, again, to explain :-)

What I think is a good thing to have is a concise document available
with the code so that if we have the code, we can just run something
like 'pydoc module' and see how to use the referred module. It could
(and IMO should) contain some example.

The idea is not put all the documentation that exists inside the
module. The idea is to put enough documentation to have a working
prototype or testing code. 

It may be a taboo here, but I made the comparison with the first page
of two modules: Perl's CGI and Python's CGI. 

I won't include the cited text again, it can be read from
python-tutor's archives or from your own systems.

The thing was that Perl's module included enough documentation to have
a start. There are more documents on the subject available in books,
on websites, etc. 

Python's module, on the other hand, gave me a description of the class
and its methods. Some of them had a nice description, other didn't. 

I'm not saying that consulting Python's standard docs (in this case
http://www.python.org/doc/current/lib/module-cgi.html) was too hard,
but it surely could be simpler. 

I use 'man' or 'info' to do read system docs, C docs, Perl docs. It
would be very interesting if something like 'pydoc' was integrated
with the system docs as is 'perldoc' and it would be even better if
the output of the documentation shown was enough to write a prototype
(even for a newbie as myself). 


<about standard library's docs>

>> Is this still gospel? Any further thoughts around this?
>
> This is still gospel for the Python standard library.

Let me make clear, here too, that this is not my intention to change
the existing docs. My intention was to add new stuff to modules so
that they can be easily understood with no additional material
(specially when people can install python in a 'defective' way without
its docs on embedded systems or production machines --- it saves 2.6
MiB here, what can be very significative in a 12 MiB flash card :-)).

-- 
Godoy.    <godoy@metalab.unc.edu>


From godoy@metalab.unc.edu  Sun May 25 21:31:19 2003
From: godoy@metalab.unc.edu (Jorge Godoy)
Date: Sun, 25 May 2003 17:31:19 -0300
Subject: [Doc-SIG] Re: [Tutor] Documentation concerns. (LONG POST)
References: <5.2.1.1.0.20030523022201.01f05c00@www.thinkware.se>
 <013801c32040$9fb80960$6401a8c0@xp>
 <5.2.0.9.0.20030520062251.027be6e8@66.28.54.253>
 <5.2.0.9.0.20030521112455.0387da20@66.28.54.253>
 <5.2.1.1.0.20030523022201.01f05c00@www.thinkware.se>
 <5.2.1.1.0.20030523223300.01efca58@www.thinkware.se>
 <m3znlduv1p.fsf@ieee.org>
 <5.2.1.1.0.20030524103225.01edd0a8@www.thinkware.se>
 <1053804978.1167.49.camel@lothlorien>
Message-ID: <m33cj2rco8.fsf@ieee.org>

Ian Bicking <ianb@colorstudy.com> writes:

> One issue I see with moving the documentation into the code, is that
> we don't have any system that can represent the kind of
> documentation from the standard library as docstrings.  Typically
> documentation created from docstrings is highly (overly) structured,
> and does not allow items to be introduced in an order different from
> the code, or presented with a different structure than the code,
> plus there is no place for narrative that is not connected with a
> function or class.

On the other hand, putting an introductory text is possible.

I'm sorry for the long post, but I wished giving a simple example. 

,----[ example.py ]----------------------------------------------------
#!/usr/bin/python -tt
#
# Demonstration file for everybody at python-tutor and crossposted 
# people.
#
# $Author: $ (somebody@somewhere.overthe.net)
# $Date: $
#
# This is a demonstration on how introductory texts can be used to 
# give better documentation, specially for newbies, including 
# examples and an introductory text.
#
# All other docstrings can be maintained as they are.
# 
# Note that I've included CVS keywords and an email for further
# contact on improving this module (or its documentation).
#
# Usage:
#
#      import DemoClass
#      checktemp = DemoClass(100, 'Celsius')
#
#      # Here be functions to read the temperature from somewhere.
#      # Lets suppose it was 89 Celsius degrees (water boils at 100
#      # Celsius degrees)
#      temperature = 89
#
#      if checktemp.IsBoiling(temperature):
#          print "Turn it off. It's boiling."
#      else:
#          print "Not ready yet."
#
#
# The rest of this document describes DemoClass' implementation. You
# should read it carefully to understand the above example and some
# other details.

# $Log: $

# Just an example of imported modules...
import os
import sys

class DemoClass:
    """
    This is a demonstration class. It does nothing useful.

    This demonstration class was written to show as an example of what
    I had in my mind about a more complete documentation inside of
    modules.

    My main concern is with having usage example and a more complete
    document than one with only the methods syntax and classes
    available with (or inherited by) the module.
    """

    def __init__(self, var = 'default', othervar = 'other default'):
        """
        Initializes DemoClass and set values for 'var' and 'othervar'

        DemoClass has 'default' as a default value for 'var', which
        describes something in the system. It could be the default
        temperature where the water boils.

        'othervar', with a default value of 'other default' represent
        something else. It could be the unit used to measure the
        temperature (after all, we must know if we're working with
        Celsius or Fahrenheit).
        """

        self.var = var
        self.othervar = othervar


    def IsBoiling(self, temp_read):
        """
        Checks if the water is boiling. Returns None if it isn't.

        IsBoiling receives the read temperature. If it is the same
        temperature that is available from self.var, it returns '1',
        otherwise it returns None.
        """

        if (temp_read == self.var):
            return 1
        else:
            return None


def main():
    """
    Main function for the program. Calls all other functions.
    """

    checktemp = DemoClass(100, 'Celsius')

    # Here be functions to read the temperature from somewhere.
    # Lets suppose it was 89 Celsius degrees (water boils at 100
    # Celsius degrees)
    temperature = 89

    if checktemp.IsBoiling(temperature):
        print "Turn it off. It's boiling."
    else:
        print "Not ready yet."


if __name__ == '__main__':
    main()
----------------------------------------------------------------------

The resulting output is:

,----[ pydoc ./example.py ]-------------------------------------------
Python Library Documentation: module example

NAME
    example

FILE
    /home/godoy/tempo/example.py

DESCRIPTION
    # Demonstration file for everybody at python-tutor and crossposted
    # people.
    #
    # $Author: $ (somebody@somewhere.overthe.net)
    # $Date: $
    #
    # This is a demonstration on how introductory texts can be used to
    # give better documentation, specially for newbies, including
    # examples and an introductory text.
    #
    # All other docstrings can be maintained as they are.
    #
    # Note that I've included CVS keywords and an email for further
    # contact on improving this module (or its documentation).
    #
    # Usage:
    #
    #      import DemoClass
    #      checktemp = DemoClass(100, 'Celsius')
    #
    #      # Here be functions to read the temperature from somewhere.
    #      # Lets suppose it was 89 Celsius degrees (water boils at 100
    #      # Celsius degrees)
    #      temperature = 89
    #
    #      if checktemp.IsBoiling(temperature):
    #          print "Turn it off. It's boiling."
    #      else:
    #          print "Not ready yet."
    #
    #
    # The rest of this document describes DemoClass' implementation. You
    # should read it carefully to understand the above example and some
    # other details.

CLASSES
    DemoClass

    class DemoClass
     |  This is a demonstration class. It does nothing useful.
     |
     |  This demonstration class was written to show as an example of what
     |  I had in my mind about a more complete documentation inside of
     |  modules.
     |
     |  My main concern is with having usage example and a more complete
     |  document than one with only the methods syntax and classes
     |  available with (or inherited by) the module.
     |
     |  Methods defined here:
     |
     |  IsBoiling(self, temp_read)
     |      Checks if the water is boiling. Returns None if it isn't.
     |
     |      IsBoiling receives the read temperature. If it is the same
     |      temperature that is available from self.var, it returns '1',
     |      otherwise it returns None.
     |
     |  __init__(self, var='default', othervar='other default')
     |      Initializes DemoClass and set values for 'var' and 'othervar'
     |
     |      DemoClass has 'default' as a default value for 'var', which
     |      describes something in the system. It could be the default
     |      temperature where the water boils.
     |
     |      'othervar', with a default value of 'other default' represent
     |      something else. It could be the unit used to measure the
     |      temperature (after all, we must know if we're working with
     |      Celsius or Fahrenheit).
     |
     |  ----------------------------------------------------------------------
     |  Data and non-method functions defined here:
     |
     |  __doc__ = '\n    This is a demonstration class. It does noth...availab...
     |
     |  __module__ = 'example'

FUNCTIONS
    main()
        Main function for the program. Calls all other functions.

DATA
    __file__ = './example.pyc'
    __name__ = 'example'
----------------------------------------------------------------------

It seems to be too much documentation for such a small module, but it
helps a lot with big ones. 

There are some modules that doesn't even generate an output when we do
'pydoc' on it (i.e., it has no docstrings at all), making it even
harder to use it (you have to go after its documentation on the
web). Of course, these aren't (up to now) included with Python in its
standard modules.



TIA,
-- 
Godoy.    <godoy@metalab.unc.edu>


From guido@python.org  Sun May 25 21:37:51 2003
From: guido@python.org (Guido van Rossum)
Date: Sun, 25 May 2003 16:37:51 -0400
Subject: [Doc-SIG] Re: [Tutor] Documentation concerns.
In-Reply-To: "Your message of Sun, 25 May 2003 16:53:35 -0300."
 <m3fzn2ref4.fsf@ieee.org>
References: <5.2.1.1.0.20030523022201.01f05c00@www.thinkware.se>
 <013801c32040$9fb80960$6401a8c0@xp>
 <5.2.0.9.0.20030520062251.027be6e8@66.28.54.253>
 <5.2.0.9.0.20030521112455.0387da20@66.28.54.253>
 <5.2.1.1.0.20030523022201.01f05c00@www.thinkware.se>
 <5.2.1.1.0.20030523223300.01efca58@www.thinkware.se> <m3znlduv1p.fsf@ieee.org>
 <5.2.1.1.0.20030524103225.01edd0a8@www.thinkware.se>
 <200305241803.h4OI31w27894@pcp02138704pcs.reston01.va.comcast.net>
 <m3fzn2ref4.fsf@ieee.org>
Message-ID: <200305252037.h4PKbp505168@pcp02138704pcs.reston01.va.comcast.net>

Jorge,

I think it would be great if every important module's doc string
contained a short introduction to its use with an example.  Perhaps
you can get us started by posting a patch for your favorite module to
SF?

--Guido van Rossum (home page: http://www.python.org/~guido/)


From grubert@users.sourceforge.net  Mon May 26 07:03:45 2003
From: grubert@users.sourceforge.net (grubert@users.sourceforge.net)
Date: Mon, 26 May 2003 08:03:45 +0200 (CEST)
Subject: [Doc-SIG] Re: [Tutor] Documentation concerns.
In-Reply-To: <m33cj2rco8.fsf@ieee.org>
References: <5.2.1.1.0.20030523022201.01f05c00@www.thinkware.se>
 <013801c32040$9fb80960$6401a8c0@xp> <5.2.0.9.0.20030520062251.027be6e8@66.28.54.253>
 <5.2.0.9.0.20030521112455.0387da20@66.28.54.253>
 <5.2.1.1.0.20030523022201.01f05c00@www.thinkware.se>
 <5.2.1.1.0.20030523223300.01efca58@www.thinkware.se> <m3znlduv1p.fsf@ieee.org>
 <5.2.1.1.0.20030524103225.01edd0a8@www.thinkware.se> <1053804978.1167.49.camel@lothlorien>
 <m33cj2rco8.fsf@ieee.org>
Message-ID: <Pine.LNX.4.51.0305260801080.1155@b52.b.ssg.co.at>

a possible split would be:

* the module reference is in docstrings
* there might be a user manaual for bigger ones
* and even a (maybe two) tutorials for large ones.

too trivial ? already done ?

-- 
 BINGO: pure play b to b in the real world
 --- Engelbert Gruber -------+
  SSG Fintl,Gruber,Lassnig  /
  A6170 Zirl   Innweg 5b   /
  Tel. ++43-5238-93535 ---+


From ianb@colorstudy.com  Mon May 26 08:58:56 2003
From: ianb@colorstudy.com (Ian Bicking)
Date: 26 May 2003 02:58:56 -0500
Subject: [Doc-SIG] Re: [Tutor] Documentation concerns.
In-Reply-To: <Pine.LNX.4.51.0305260801080.1155@b52.b.ssg.co.at>
References: <5.2.1.1.0.20030523022201.01f05c00@www.thinkware.se>
 <013801c32040$9fb80960$6401a8c0@xp>
 <5.2.0.9.0.20030520062251.027be6e8@66.28.54.253>
 <5.2.0.9.0.20030521112455.0387da20@66.28.54.253>
 <5.2.1.1.0.20030523022201.01f05c00@www.thinkware.se>
 <5.2.1.1.0.20030523223300.01efca58@www.thinkware.se>
 <m3znlduv1p.fsf@ieee.org>
 <5.2.1.1.0.20030524103225.01edd0a8@www.thinkware.se>
 <1053804978.1167.49.camel@lothlorien> <m33cj2rco8.fsf@ieee.org>
 <Pine.LNX.4.51.0305260801080.1155@b52.b.ssg.co.at>
Message-ID: <1053935935.738.15.camel@lothlorien>

On Mon, 2003-05-26 at 01:03, grubert@users.sourceforge.net wrote:
> a possible split would be:
> 
> * the module reference is in docstrings
> * there might be a user manaual for bigger ones
> * and even a (maybe two) tutorials for large ones.

In a similar One thing I've played with is being able to reference the
docstrings, so you can put some reference information in the docstrings,
and then inline those into the documentation.  I played around with a
reST hack that did something like:

# module docstring:
"""
The foo module provides X, Y, and Z, but all functionality is provided
through the `Foo` class:

.. inline: Foo
"""

class Foo:
    """
    yada yada.  Pay particular attention to the `bar` method.

    .. inline: bar
    """

    def bar(self):
        """and so on..."""

Another option might be to use such inlining in the external document. 
Then you can interject narrative, reorder and exclude things, but you
avoide duplicate documentation.

For another document, I've been using something that strips examples
from a script (marked with special comments), and turns them into
highlighted source snippets that can be included.  Kind of a similar
idea.

  Ian




From cben@techunix.technion.ac.il  Mon May 26 10:44:44 2003
From: cben@techunix.technion.ac.il (Beni Cherniavsky)
Date: Mon, 26 May 2003 12:44:44 +0300 (IDT)
Subject: [Doc-SIG] Re: [Tutor] Documentation concerns.
In-Reply-To: <1053935935.738.15.camel@lothlorien>
References: <5.2.1.1.0.20030523022201.01f05c00@www.thinkware.se>
 <013801c32040$9fb80960$6401a8c0@xp>  <5.2.0.9.0.20030520062251.027be6e8@66.28.54.253>
 <5.2.0.9.0.20030521112455.0387da20@66.28.54.253>
 <5.2.1.1.0.20030523022201.01f05c00@www.thinkware.se>
 <5.2.1.1.0.20030523223300.01efca58@www.thinkware.se>  <m3znlduv1p.fsf@ieee.org>
 <5.2.1.1.0.20030524103225.01edd0a8@www.thinkware.se>  <1053804978.1167.49.camel@lothlorien>
 <m33cj2rco8.fsf@ieee.org>  <Pine.LNX.4.51.0305260801080.1155@b52.b.ssg.co.at>
 <1053935935.738.15.camel@lothlorien>
Message-ID: <Pine.GSO.4.51.0305261228130.12701@techunix.technion.ac.il>

Ian Bicking wrote on 2003-05-26:

> On Mon, 2003-05-26 at 01:03, grubert@users.sourceforge.net wrote:
> > a possible split would be:
> >
> > * the module reference is in docstrings
> > * there might be a user manaual for bigger ones
> > * and even a (maybe two) tutorials for large ones.
>
> In a similar One thing I've played with is being able to reference the
> docstrings, so you can put some reference information in the docstrings,
> and then inline those into the documentation.  I played around with a
> reST hack that did something like:
>
> # module docstring:
> """
> The foo module provides X, Y, and Z, but all functionality is provided
> through the `Foo` class:
>
> .. inline: Foo
> """
>
> class Foo:
>     #snipped...
>
> Another option might be to use such inlining in the external document.
> Then you can interject narrative, reorder and exclude things, but you
> avoide duplicate documentation.
>
> For another document, I've been using something that strips examples
> from a script (marked with special comments), and turns them into
> highlighted source snippets that can be included.  Kind of a similar
> idea.
>
Having all info inside the document itself is better because when
editing you can see it all.  If the docstrings are included later, you
might not notice when they change and the documentation can get out of
sync.  Even if the docstrings and the exrnal doc don't conradict each
other, it's harder to ensure that they cover all material without gaps
or too much overlap.  Of course, it's good practice to render the
final documentation and read it from time to time but you woulnd't do
it every 2 minutes, right?

I think the best solution is to have a tool that includes the
docstrings into your source while leaving some markers around it, so
that it is idempotent when run upon its own output.  Then you can
directly edit this output like it would appear at the end but you can
sync it to the docstrings at any moment by re-running the tool.

Supporting evidence: I'm now working on a reST document that includes
examples of logical-order strings and the result of applying the
unicode bidi algorithm on them.  Doing it manually would be
error-prone.  So I wrote a python script that leaves all unrecognized
text as-is but recomputes the visual-order results from the logical
order inputs and bound a key in emacs to filtering the region with it.
Now it's extremely convenient because I can see when writing what
precisely will the example teach my reader and things can't get out of
sync...

-- 
Beni Cherniavsky <cben@users.sf.net>


From ianb@colorstudy.com  Mon May 26 20:46:17 2003
From: ianb@colorstudy.com (Ian Bicking)
Date: 26 May 2003 14:46:17 -0500
Subject: [Doc-SIG] Re: [Tutor] Documentation concerns.
In-Reply-To: <Pine.GSO.4.51.0305261228130.12701@techunix.technion.ac.il>
References: <5.2.1.1.0.20030523022201.01f05c00@www.thinkware.se>
 <013801c32040$9fb80960$6401a8c0@xp>
 <5.2.0.9.0.20030520062251.027be6e8@66.28.54.253>
 <5.2.0.9.0.20030521112455.0387da20@66.28.54.253>
 <5.2.1.1.0.20030523022201.01f05c00@www.thinkware.se>
 <5.2.1.1.0.20030523223300.01efca58@www.thinkware.se>
 <m3znlduv1p.fsf@ieee.org>
 <5.2.1.1.0.20030524103225.01edd0a8@www.thinkware.se>
 <1053804978.1167.49.camel@lothlorien> <m33cj2rco8.fsf@ieee.org>
 <Pine.LNX.4.51.0305260801080.1155@b52.b.ssg.co.at>
 <1053935935.738.15.camel@lothlorien>
 <Pine.GSO.4.51.0305261228130.12701@techunix.technion.ac.il>
Message-ID: <1053978376.731.26.camel@lothlorien>

On Mon, 2003-05-26 at 04:44, Beni Cherniavsky wrote:
> Having all info inside the document itself is better because when
> editing you can see it all.  If the docstrings are included later, you
> might not notice when they change and the documentation can get out of
> sync.  Even if the docstrings and the exrnal doc don't conradict each
> other, it's harder to ensure that they cover all material without gaps
> or too much overlap.  Of course, it's good practice to render the
> final documentation and read it from time to time but you woulnd't do
> it every 2 minutes, right?
> 
> I think the best solution is to have a tool that includes the
> docstrings into your source while leaving some markers around it, so
> that it is idempotent when run upon its own output.  Then you can
> directly edit this output like it would appear at the end but you can
> sync it to the docstrings at any moment by re-running the tool.

Like maybe, say:

.. inline Foo

(stuff taken from Foo's docstring)

.. end inline

And instead of making this a directive, it is a pre-compiler, where
everything between ".. inline Foo" and ".. end inline" is derivative
(and so shouldn't be edited, but can be read).

Of course, it should support more than just inlining docstrings, as
there's already two other examples of inlining that we want to use, and
no doubt more are likely.  

But it is a little crude to use a preprocessor.  That seems integral,
though, without some sort of powerful IDE that dynamically inlined such
documentation.

  Ian




From cben@techunix.technion.ac.il  Tue May 27 17:19:52 2003
From: cben@techunix.technion.ac.il (Beni Cherniavsky)
Date: Tue, 27 May 2003 19:19:52 +0300 (IDT)
Subject: [Doc-SIG] Re: [Tutor] Documentation concerns.
In-Reply-To: <1053978376.731.26.camel@lothlorien>
References: <5.2.1.1.0.20030523022201.01f05c00@www.thinkware.se>
 <013801c32040$9fb80960$6401a8c0@xp>  <5.2.0.9.0.20030520062251.027be6e8@66.28.54.253>
 <5.2.0.9.0.20030521112455.0387da20@66.28.54.253>
 <5.2.1.1.0.20030523022201.01f05c00@www.thinkware.se>
 <5.2.1.1.0.20030523223300.01efca58@www.thinkware.se>  <m3znlduv1p.fsf@ieee.org>
 <5.2.1.1.0.20030524103225.01edd0a8@www.thinkware.se>  <1053804978.1167.49.camel@lothlorien>
 <m33cj2rco8.fsf@ieee.org>  <Pine.LNX.4.51.0305260801080.1155@b52.b.ssg.co.at>
 <1053935935.738.15.camel@lothlorien>  <Pine.GSO.4.51.0305261228130.12701@techunix.technion.ac.il>
 <1053978376.731.26.camel@lothlorien>
Message-ID: <Pine.GSO.4.51.0305271628210.14714@techunix.technion.ac.il>

Ian Bicking wrote on 2003-05-26:

> On Mon, 2003-05-26 at 04:44, Beni Cherniavsky wrote:
> > Having all info inside the document itself is better because when
> > editing you can see it all.  If the docstrings are included later, you
> > might not notice when they change and the documentation can get out of
> > sync.  Even if the docstrings and the exrnal doc don't conradict each
> > other, it's harder to ensure that they cover all material without gaps
> > or too much overlap.  Of course, it's good practice to render the
> > final documentation and read it from time to time but you woulnd't do
> > it every 2 minutes, right?
> >
> > I think the best solution is to have a tool that includes the
> > docstrings into your source while leaving some markers around it, so
> > that it is idempotent when run upon its own output.  Then you can
> > directly edit this output like it would appear at the end but you can
> > sync it to the docstrings at any moment by re-running the tool.
>
> Like maybe, say:
>
> .. inline Foo
>
> (stuff taken from Foo's docstring)
>
> .. end inline
>
> And instead of making this a directive, it is a pre-compiler, where
> everything between ".. inline Foo" and ".. end inline" is derivative
> (and so shouldn't be edited, but can be read).
>
Yes, more or less so.

> Of course, it should support more than just inlining docstrings, as
> there's already two other examples of inlining that we want to use, and
> no doubt more are likely.
>
Of course.  This is relevant to any kind of inlining mechanism.

> But it is a little crude to use a preprocessor.  That seems integral,
> though, without some sort of powerful IDE that dynamically inlined such
> documentation.
>
Emacs, with a key bound to filtering the region through it?  And/or a
makefile target to update all files?  The point is to make the
preprocessor safe and idempotent and then have it work in-place
instead of the classical approach of separate source and generated
files.

For extra polish it seems to make sense to omit the inlined texts in
cvs.  OTOH, then cvs will not detect conflicts between the narrative
and the inlined texts.

-- 
Beni Cherniavsky <cben@users.sf.net>

The Three Laws of Copy-Protechnics:
http://www.technion.ac.il/~cben/threelaws.html


From pearu at cens.ioc.ee  Sat May 31 22:58:07 2003
From: pearu at cens.ioc.ee (Pearu Peterson)
Date: Sat May 31 14:58:41 2003
Subject: [Doc-SIG] chunk in docutils CVS
Message-ID: <Pine.LNX.4.21.0305312153320.14353-100000@cens.kybi>


Hi,

I just updated my local docutils CVS repository
and got also lots of chunk that appears to be
the contents of CVSROOT directory. Thought you
should know..

Regards,
	Pearu