[DOC-SIG] Re: [PYTHON DOC-SIG] contributing documentation

[Andrew Kuchling]

> Is there an example of a properly documented module to work from?  I would
> not like to produce some stuff only to find out that it is not in the
> preferred format.  I assume we're talking about doc strings, internal
> documentation, and something suitable for the Library Reference?

	Any or all of the above is fine; don't feel obliged to do all
three, though that would be nice.  (What's internal documentation?
Adding comments?  Probably not a high priority for that module...)

> Also, I'm not a LaTex user, is that going to be a problem?  I see docs
> posted with /cstuff{} in them that does not look familiar...
> (Again, perhaps having a template would be sufficient...) 

	libsocket.tex is very big and uses most of the available
macros; for a simple module like command.py, a simple template like
libdbm.tex is probably best.  If you can't do LaTeX, it's still useful
to just write it as a plain ASCII file, and have someone else like me
add the LaTeX formatting--it's much easier to produce the formatting
than it is to write the actual text!

	30-second LaTeX introduction: macros are preceded by \, and
may take zero or more parameters which are inside { }.  There are lots
of different predefined macros: \var{} is for parameter (=variable)
names, \code{} is for Python code.  There are also more complex
environments, which are called by \begin{environment-name} ...stuff
\end{environment-name}.  

	There are some notes on the LaTeX macros available at
http://people.magnet.com/~amk/sigs/pipermail/1997q2.doc-sig/61beb98e93ef.html

	Here's a simplified sample function, open() from libdbm.tex:
 
\begin{funcdesc}{open}{filename\, mode} 
Open a dbm database and return a dbm object.  The \var{filename}
argument is the name of the database file (without the \file{.dir} or
\file{.pag} extensions). The optional \var{mode} argument is the
\UNIX{} mode of the file, used only when the database has to be
created.  It defaults to octal \code{0666}.
\end{funcdesc}

	You could just copy the above, change the function name and
parameters, and replace the text.


	Andrew Kuchling
	amk@magnet.com
	http://people.magnet.com/%7Eamk/

_______________
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
_______________