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

Log in
Name

Password

 
 

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.