[PYTHON DOC-SIG] Templatising gendoc, and more.

[Mark Hammond]

Couple of quick questions - how can a ni package provide doc strings?  Eg, a 
package named "xyz" is a directory, _not_ a file.  I added a 
convention to gendoc that a file called "__doc__" in a packages 
directory will be read, and treated as docstrings for the module 
itself (which makes lots of sense to me, as then you dont need to 
distribute it)
Also, I "flatten" the "__init__" module, so that all docstrings and 
methods are documented in the package itself - ie, __init__ never 
gets a mention in the docs.
Do these sound OK?

Secondly - by default, there are a few places it is assumed the file 
name of the generated file is the same as the object itself.  Thus, 
the module "a.b" is created as "a.b.html".  Is it worth making a 
change to that it is created as "a_b.html"?  Up until recently, even 
Python could not correctly parse the extension from a.b.html, so Im 
inclined to think it is.
2 ways to tackle this - unconditionally replace "." with "_" in 
object names, or allow the classes to have the concept of _2_ names - 
the objects name, and the generated file name.  The latter is more 
general, but touches more code...

Now, the main one.  This may sound a little wierd and hard, but here
goes anyway...

Something I didnt really like about gendoc was the way it enforced a 
"synopsis"/"description"/"See also" type format on your documentation.  
As I read about the StructuredText module that Jim did, what I really 
expected what that _my_ structure would be used for the 
documentation.  Eg, what I expected to be able to write was:
"""Some Module:

Description
  This is the desc
Known Bugs
  Lots and lots
See Also
  Some extra stuff
Synopsis
  At the bottom! :-)
"""
and I expected that my "See Also" stuff would automatically go into 
the "See Also" section on the Web page, and that a top-level "Known 
Bugs" section would appear in the HTML - it doesnt :-(

I have a few ideas on how you could do this.

My idea is basically to have 2 modes - a "template" mode, and
a "freeform" mode.  The (default?) "template" mode is much like now,
but would use a text file of "known" section names.  Eg, the
"default" template, which would generate doc identical to now would
be like:
Synopsis|<H2>%s</H2>|<P>
Description
See Also
[The stuff after the | could be optional, and defines how the heading 
itself it rendered, and also how para in the body is pre/a-pended.  
Thats off the top of my head - consider the concept, not my impl idea 
:-)

And someone else could change it if required for their documentation 
needs.

Free-form mode would still use "known" section names, but would use 
the top-level structure of the structured doc-string to determine the 
order and inclusion of sections.  Eg, in the example above, the 
"generated" see also entries (as now) would be appended/prepended to the 
"explicit" see also entries (which the module author specifies as 
relevant, but gendoc didnt), and no "synopsis" section at all would 
be generated (which may make sense for sample modules, for example, 
where an implication of importing the sample code is not correct)

Any comments on this?

Mark.
----------------------------------------------------------------------
Mark Hammond - MHammond@skippinet.com.au 
Check out Python - _the_ language for the Web/CGI/Windows/MFC/Unix/etc
<http://www.python.org> & <http://www.python.org/ftp/python/pythonwin>

_______________
DOC-SIG  - SIG for the Python Documentation Project

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