[PYTHON DOC-SIG] Templatising gendoc, and more.
Tue, 18 Feb 1997 21:42:03 +1000
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
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
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:
This is the desc
Lots and lots
Some extra stuff
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
[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
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 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: email@example.com
administrivia to: firstname.lastname@example.org