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 _______________