History for DocumentationStrings
??changed:
-
Can the Python documentation special interest group (DOC-SIG) make use of structured text?
StructuredText was originally designed by JimFulton specifically for this purpose.
It worked pretty well for Jim, but some of the rules Jim picked, like use of single quotes
for code are controversial. There are additional rules that some people would like
that Jim didn't implement.
The beauty of StructuredTextNG is that it is now pretty easy to change the rules!
It would help if people could make some proposals (with lots of examples) for what
rules they'd like:
ClassicStructuredTextRules -- These are the classic rules, used by some
documentation systems now.
Please keep in mind a basic goal of structured text, which is to keep the raw text as
readable as possible. **If you don't buy into this idea, you're probably wasting your time.**
Note -- The ClassicStructuredTextRules break this rule with a table rule that snuck
in when Jim wasn't watching.
If you want, you can also gripe:
- MosheZadkasProblemsWithStructuredText
but proposals for ways to fix the gripes would be very helpful.
<hr>
Here is an update of what has been happening with regard to StructuredText
and Python docstrings (2001-03-06, [Tibs]):
* Moshe is in charge of
"PEP 216":http://python.sourceforge.net/peps/pep-0216.html (Docstring
Format), which is required reading.
* Work in general gets reported on the Python Doc-SIG - this is also
required reading, I'm afraid, since I don't remember to update
this page very often.
* Python 2.1 will include Ka-Ping Yee's
"pydoc", http://www.lfw.org/python/pydoc.html
tool (see also the bottom of his "Python things",
http://www.lfw.org/python/
page), which locates
Python documentation from within Python modules, and presents it
in a variety of ways (including a "man" style interaction, and
also as HTML pages). It doesn't format the insides of docstrings
(yet).
* I ([Tibs]) have been working on code to parse STpy (i.e., a Python
variant of ST/STNG) - see
"http://www.tibsnjoan.co.uk/docutils/status.html",
http://www.tibsnjoan.co.uk/docutils/status.html
for information on the current progress of this, and a link to
a document describing what it is trying to support in more detail.
The intention is that something very like STNG should be supported
by this module, as well as the Python specific extensions (although
note that because of the lack of formality of the ST/STNG formats,
the details of implementation may differ slightly).
* Doug Hellman has been working on "HappyDoc",
http://happydoc.sourceforge.net/
which is another tool (with a different emphasis to pydoc), and which
currently uses STClassic to format the inside of docstrings (and
optionally also comments. He has used it to produce a set of
ZopeSrcDocs.
* Various other tools out there will find documentation and present
it - not necessarily formatting the innards of the docstrings.
For instance, ReportLabs.
* My intention is that the new docutils code should be a plug-in
for people who want to be able to use STpy and (maybe) STNG as
well, insofar as it supports an STNG-sibling.
* EdwardLoper is producing a formal definition (using extended EBNF)
of STminus - that is, the intersection of the STNG and STpy
developments. See
"http://www.cis.upenn.edu/~edloper/pydoc/stminus.html",
http://www.cis.upenn.edu/~edloper/pydoc/stminus.html
for details.
<hr>
If you aren't comfortable adding comments in the middle of the above text, please feel free to add comments here.