[Doc-SIG] Proposal for indented sections in reStructuredText

[David Goodger]

on 2001-06-15 2:10 AM, Peter Funk (pf@artcom-gmbh.de) wrote:
> If restructured text limits itself to at most two levels, using '=' as
> a underline character for top level headings und '-' as a underline
> character for nested section headings is okay.
> 
> But IMO the different over- und underlining styles and the automatic
> recognition of styles described in your proposal is way too much freedom
> for writers.  This seems unpythonic to me.  At least for Python doc-strings
> the title style to be used should be restricted.

I want to keep reStructuredText -- the syntax markup spec -- completely
separate from the the conventions or limits imposed by Python docstrings.
Saying that any aspect of reStructuredText is "pythonic" or "unpythonic" is
a disservice. reStructuredText stands on its own, usage-neutral. I'd like to
think that reStructuredText (or any markup syntax) could be applied in a
variety of domains, just as I would defend the use of XML, POD, JavaDoc, or
TeX as perfectly valid syntaxes in Python docstrings (don't ask me to use
them though). Whether the biases or familiarities which attract individuals
to Python also attract them to a certain docstring markup syntax... ;-)

Having said that (let me switch perspectives here), if the docstring
conventions were to specify a subset of reStructuredText, that would be
fine.

And yes, I know that I am guilty of conflict of interest regarding
reStructuredText and the Docstring Processing System projects. I'm guilty of
making decisions for reStructuredText based on "pythonic" criteria, of
trying to appeal to the Python community and its final arbiter. Perhaps I
should clean up my act and remove all inter-project contamination? Nah.

Sometimes I take all of this too seriously.

-- 
David Goodger    dgoodger@bigfoot.com    Open-source projects:
 - Python Docstring Processing System: http://docstring.sf.net
 - reStructuredText: http://structuredtext.sf.net
 - The Go Tools Project: http://gotools.sf.net