[PYTHON DOC-SIG] Documentation format

[Andrew Kuchling]

Guido van Rossum wrote:
> never be contained in docstrings).  How feasible is @texinfo or ILU's
> TIM (which looks like an extension of @texinfo)?

	I wrote my SSLeay documentation in Texinfo, and it was no
difficulty; however, it's a lot smaller than the library reference.
Documentation for an object method looks like this:

@defmethod @r{SSLconn objects} use_certificate_file (@var{filename})
Set the X.509 certificate to be used; @var{filename} is the name of a
file containing an X.509 certificate encoded in PEM format.
@end defmethod

	The HTML output looks like this in Lynx:

   use_certificate_file (filename) -- Method on SSLconn objects
          Set the X.509 certificate to be used; filename is the name
          of a file containing an X.509 certificate encoded in PEM 
          format.

	We'd still need to think about things like default values and
keyword arguments.  Perhaps something like (following TIM's lead):

@defmethod @r{object} func (@keyword{filename} filename @default{@file{/etc/passwd}})
  ...text...
Not very readable, is it?  <sigh>  Anyway, it could then be formatted
into something like:
   
  func (<bold>filename</bold>= <ital>filename</ital> [/etc/passwd] )
        ...text...

	(There may be a good argument to be made for putting default
argument values into the text here.  Ah well, that's a typographical
question independent of the formatter used.)


	Andrew Kuchling
	amk@magnet.com

=================
DOC-SIG  - SIG for the Python Documentation Project

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