[Doc-SIG] Docstrings Format

[Ken Manheimer]

On Mon, 6 Nov 2000, Moshe Zadka wrote:

> On Mon, 6 Nov 2000, Ken Manheimer wrote:
> 
> >     1. It must be easy to type with any standard text editor.
> >     2. It must be readable to the casual observer.
> >     4. It must contain sufficient information so it can be converted
> >        to any reasonable markup format.
> 
> I disagree with "4": I cannot mark up things like "this is a Python
> variable". If you show me how to extend StructuredText for these
> kind of things, it would definitely get a chance. Please have
> a look at the PEP and see the exact markup goals I've outlined. Of 
> course, if you do not agree with the goals, you can say that too...

StructuredTextNG was specifically developed to be extensible, and has some
substantial documentation (i hear) to get you going.  (The documentation
covers extending the expressions that are recognized, but not yet creating 
outputters, responsible for rendering whatever presentation you
want.)  See:

  http://www.zope.org/Members/jim/StructuredTextWiki/StructuredTextNG

> Nothing is "unacceptable", but as I've explained earlier, StructuredText
> as is has not enough strength to do arbitrary Python-specific markup.

See whether StructuredTextNG's extensibility would give you what you want.

-- 
Ken
klm@digicool.com