[Python-Dev] Re: Docutils/reStructuredText is ready to proces s PEPs

[Delaney, Timothy]

> From: Ka-Ping Yee [mailto:python-dev@zesty.ca]
> 
> One can separate two issues here:
> 
>     1. too much functionality (YAGNI)
>     2. too many ways of expressing the same functionality (TMTOWTDI)

>From my reading of the reST docs at various times, I've come to the
conclusion that YAGNI doesn't apply - that each of the features exists
because someone *did* need it (i.e. they had a real use case for it).

I do feel that the explanations of some of the constructs are somewhat
confusing. I think all constructs should include at least one (and
preferably more) use cases in their explanations.

Personally, I'm in favour of having the complete reST specification, but
have well-defined conventions for usage of reST within specific
applications. So a "docstring convention" document would specify what the
structure of a docstring should (or must) include, how it is parsed, what
interpreted text means, etc. Fairly comprehensive examples should be
included. Unless you had  very specific need you shouldn't go outside of the
convention, but it should be available if you needed it for something which
couldn't be expressed otherwise.

If all you wanted to do was write docstrings, you would refer to the
docstring convention document.

If you wanted to write a PEP, you would refer to the PEP convention
document.

Because they use the same underlying syntax, knowning how to do one will
help with learning how to do the other. One may normally use more (or
different) constructs than the other, but there will be a lot of crossover.


Tim Delaney