Larry Hastings wrote:
Ron Adam wrote:
Thanks for the link. PEP 287 looks to be fairly general in that it expresses a general desire rather than a specification. I thought it was pretty specific. I'd summarize PEP 287 by quoting entry #1 from its "goals of this PEP" section:
* To establish reStructuredText as a standard structured plaintext format for docstrings (inline documentation of Python modules and packages), PEPs, README-type files and other standalone documents.
Rather than fixing on a standard markup, I would like to see support for a __markup__ module variable which specifies the specific markup language that is used in that module. Doc processors could inspect that variable and then load the appropriate markup translator. I guess I'll go for the whole-hog +1.0 here. I was going to say +0.8, citing "There should be one---and preferably only one---obvious way to do it.". But I can see organizations desiring something besides ReST,
Talin wrote: like if they already had already invested in their own internal standardized markup language and wanted to use that.
This makes the future clear; the default __markup__ in 2.6 would be "plain", so that all the existing docstrings work unmodified. At which point PEP 287 becomes "write a ReST driver for the new pydoc". Continuing my dreaming here, Python 3000 flips the switch so that the default __markup__ is "ReST", and the docstrings that ship with Python are touched up to match---or set explicitly to "plain" if some strange necessity required it.
(And when do you unveil DocLobster?)
Well, I'd be more interested in working on it once there's something to plug it into - I didn't really want to write a whole pydoc replacement, just a markup transformer. One issue that needs to be worked out, however, is the division of responsibility between markup processor and output formatter. Does a __markup__ plugin do both jobs, or does it just do parsing, and leave the formatting of output to the appropriate HTML / text output module? How does the HTML output module know how to handle non-standard metadata? Let me give an example: Suppose you have a simple markup language that has various section tags, such as "Author", "See Also", etc.: """ Description: A long description of this thing whatever it is. Parameters: fparam - the first parameter sparam - the second parameter Raises: ArgumentError - when invalid arguments are passed. Author: Someone See Also: PyDoc ReST """ So the parser understands these various section headings - how does it tell the HTML output module that 'Author' is a section heading? Moreover, in the case of "Parameters" and "Exceptions", the content of the section is parsed as a table (parameter, description) which is stored as a list of tuples, whereas the content of the "Description" section is just a long string. I guess the markup processor has to deliver some kind of DOM tree, which can be rendered either into text or into HTML. CSS can take over from that point on. -- Talin