PEP 287: reStructuredText Standard Docstring Format
mmh, Q: can we see the html doc produced starting from all the modules of a minimal example package? for the rest: [from PEP] 1. To establish a standard docstring format by attaining "accepted" status (Python community consensus; BDFL pronouncement). Once reStructuredText is a Python standard, all effort can be focused on tools instead of arguing for a standard. Python needs a standard set of documentation tools. Really? establish in what sense? BDFL blessing is not sufficient in this case, or is it? especially since this is gonna be a nop for the std lib, and the std doc (for a long moment). Once a standard exists, people will start to use it, and momentum will inevitably gather. This is rather naive. The only thing I found relevant in the PEP are (does this fact means something?): - Markup that isolates a Python identifier: interpreted text. - Markup that isolates a Python identifier and specifies its type: interpreted text with roles. An approach (maybe just even a presentation approach) that focus on the relevant and minimality, will be easier to push down people throat, from the Q&A and the PEP it seems that the PEP is the result of a motivated self-selected group with difficulty to reach consensus and so neglecting minimality...
[me]
The only thing I found relevant in the PEP are (does this fact means something?):
- Markup that isolates a Python identifier: interpreted text.
- Markup that isolates a Python identifier and specifies its type: interpreted text with roles.
Ok there's another relevant bit: - Markup for "tagged lists" or "label lists": field lists. ... They may be used to implement docstring semantics, such as identifying parameters, exceptions raised, etc.; such usage is beyond the scope of this PEP. how many eons would pass before we see a PEP about those *relevant* issues? Presumably JavaDoc is a good start point for this <wink>. More or less JavaDoc tags would map to fields, except @see and @link that would use `interp-text` and the various ref/links forms. regards.
From: Fredrik Lundh <fredrik@pythonware.com>
samuele wrote:
how many eons would pass before we see a PEP about those *relevant* issues? Presumably JavaDoc is a good start point for this <wink>.
do you need a PEP, or is it okay if I just post some code?
Code please, see code is less controversial than PEPs... [From PEP 287] The lack of a standard syntax for docstrings has hampered the development of standard tools for extracting docstrings and transforming them into documentation in standard formats (e.g., HTML, DocBook, TeX). There have been a number of proposed markup formats and variations, and many tools tied to these proposals, but without a standard docstring format they have failed to gain a strong following and/or floundered half-finished. Honestly, is that true? JavaDoc would be useful even if it didn't allow HTML but just the @tags, IOW rich formatting is a very secondary issue, indeed programmers are lazy and the important part of JavaDoc is getting proper inter-references and bind the information that can be extracted from code (parms) with their doc description. OTOH Perl POD is used for the standard doc for Perl modules. The API doc that comes from Sun is html produced out of the JavaDoc markup. Python standard doc should be specified in the format described at http://www.python.org/doc/2.2p1/doc/doc.html, let's refer to it as py-tex-markup how does the PEP relate to producing from inline docstrings at least a first cut in a subset of the py-tex-markup format? indeed py-tex-markup is maybe overkill for the casual module, but the issue is also that there is not a tool that produce it from the docs inside a casual module (or there is such tool???), and on the same line of reasoning reST is also maybe overkill especially if it does translate to py-tex-markup considering-every-module-dreams-to-become-a-standard-module-and- -receive-BDFL-blessing-ly y'rs
[Samuele Pedroni, re docstring semantics]
how many eons would pass before we see a PEP about those *relevant* issues? Presumably JavaDoc is a good start point for this <wink>.
[Fredrik Lundh]
do you need a PEP, or is it okay if I just post some code?
[Samuele Pedroni]
Code please, see code is less controversial than PEPs...
Go ahead, Fredrik, post some code. If we're lucky, it won't be piled on to the trash heap of past experiments. If you're serious and not just being snide, I look forward to the results. -- David Goodger goodger@users.sourceforge.net Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net
Samuele Pedroni wrote:
do you need a PEP, or is it okay if I just post some code?
Code please, see code is less controversial than PEPs...
some code can be found via this link: http://online.effbot.org/2002_04_01_archive.htm#75103766 the pythondoc parser can handle all modules in the xmltoys kit, but it hasn't been tested with much external code. out- puts both (preliminary, rather simple-minded) XML and a truly minimalistic HTML variant. requires Python 2.2 at the moment; haven't tested it under Jython yet. see TODO entries in xmltoys/PythonDoc for a list of known issues. enjoy /F
I wrote:
Code please, see code is less controversial than PEPs...
some code can be found via this link:
http://online.effbot.org/2002_04_01_archive.htm#75103766
the pythondoc parser can handle all modules in the xmltoys kit, but it hasn't been tested with much external code. out- puts both (preliminary, rather simple-minded) XML and a truly minimalistic HTML variant.
an updated version can be found at: http://effbot.org/downloads/index.cgi/xmltoys-1.0a4-20020407.zip (click on download to get the code, click on the .html links to see examples rendered by the current HTML renderer) http://effbot.org/guides/pythondoc.htm (overview description, in progress) this version has been tested with itself, PIL, and a couple of other rather large libraries. unlike the first release, it can also parse the python standard library without getting stuck on None objects (but for obvious reasons, it doesn't generate any output for the standard library... not yet, at least ;-) it still requires Python 2.2; I'll fix the HTMLParser dependecy really soon now... enjoy /F
participants (3)
-
David Goodger -
Fredrik Lundh -
Samuele Pedroni