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. > > > Talin wrote: >> 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, > 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 _______________________________________________ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com