[Python-Dev] PEP 287: reStructuredText Standard Docstring Format

[Samuele Pedroni]

mmh,

Q: can we see the html doc produced
starting from all the modules of a
minimal example package?

for the rest:
[from PEP]


    1. To establish a standard docstring format by attaining
       "accepted" status (Python community consensus; BDFL
       pronouncement).  Once reStructuredText is a Python standard,
       all effort can be focused on tools instead of arguing for a
       standard.  Python needs a standard set of documentation tools.

Really? establish in what sense? BDFL blessing is not sufficient
in this case, or is it? especially since this is gonna be a nop for the
std lib, and the std doc (for a long moment).

        Once a standard exists, people will start to use
       it, and momentum will inevitably gather.

This is rather naive.

The only thing I found relevant in the PEP are
(does this fact means something?):


    - Markup that isolates a Python identifier: interpreted text.

    - Markup that isolates a Python identifier and specifies its type:
      interpreted text with roles.

An approach (maybe just even a presentation approach)
 that focus on the relevant and minimality,
will be easier to push down people throat,
from the Q&A and the PEP it seems that the PEP is the
result of a motivated self-selected group 
with difficulty to reach consensus and
so neglecting minimality...
>From the PEP:

    [[Are these in fact the goals of the Doc-SIG members?  Anything to
    add?]]

    Throughout the existence of the Doc-SIG, consensus on a single
    standard docstring format has never been reached.  

so is this just your proposal? how should we
parse that?  
To be honest the point is not what the
goal of the Doc-SIG are, but what
the PEP can do for us.


My experience with JavaDoc is that
people maybe will do the little effort
required, 
if they know: I do this little markup
and I get this set of useful htmls
that I can put online, e.g.
<http://jrgp.sourceforge.net/doc/gap/index.html>

[I'm not arguing in favor of JavaDoc,
because I know that plain-text-resemblance
is a goal for python docstrings and not for
JavaDoc, on the other hand the PEP make
some strectched assumptions about what
is readability
in source code and the fact that a 'apropos'
function doing the right stripping cannot be
more than OK for interactive use of the __doc__,]


The PEP focus seems out of focus:
are you asking whether a brand-new 
rich formatting markup
can be used for rich formatting? ye, then what...
it can be easely hated too.

IOW I mean that the motivation points 1.-4
in Rationale,
do not constitute a crystal-clear rationale,
I would argue what kind of structure 2.
is talking about and it seems that the PEP
goes well beyond the kind of structure
that the average programmer need and
OTOH it seems it has anything to do with
the structure of the doc produced by
extract-to-documentation tools: what happens
if I put 3 level of titles in the doc of
a method? oops, ye the abstract says that the
PEP is not concerned with this

[after some more tought]
Now, I see the issue is reST vs. HTML and
not JavaDoc vs. reST. Ahaha.

So the PEP can only be judged once
we can see the reST-ed module ->
tex for the std lib doc trip, or is even not
about that?

the goal as stated are rich docstrings (for
what?) and PEPs...

I'm puzzled, the PEP
does not even refer or cite PEP 257,
which OTOH seem also not to address
completly the issue of doc-extraction tools interaction.

Honestly, 
PEP 256,257,258, PEP 287
where are we going?

One could even argue that the effort necessary
to implement reST, is wasted wrt to the goal
of having a packages -> useful doc output chain (?),

Generality is good but a design driven but at least
by *one* *definite* *kind* *of* *output* would not be a bad thing
either...  I don't see a clear picture of the input -> output
relation in all the PEPs, 

Maybe goal 1 should be honestly rephrased:

    1. To establish a standard docstring format by attaining...

=>

    1. To establish a standard docstring 
       *rich formatting* format *for the interested* by attaining

( Btw, many people will not react simply because they don't care
and are not going to use this anyway, but some
people already "hate" the PEP, that's not a good sign,
and BDFL support is not sufficient here IMHO, you
got at least the politics wrong IMHO)

regards.