[Python-Dev] PEP 287: reStructuredText Standard Docstring Format (original) (raw)

Samuele Pedroni pedroni@inf.ethz.ch
Thu, 4 Apr 2002 16:33:48 +0200

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.