You are not logged in Log in Join
You are here: Home » Members » jim » StructuredTextWiki » DocumentationStrings

Log in
Name

Password

 
 
FrontPage » StructuredTextNG » CurrentIssues »

DocumentationStrings

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:

but proposals for ways to fix the gripes would be very helpful.


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 (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 tool (see also the bottom of his Python things 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 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 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 for details.


If you aren't comfortable adding comments in the middle of the above text, please feel free to add comments here.