[docs] Documentation style conventions?

Jes Slow cluelesscoder at gmail.com
Wed Oct 3 20:55:27 CEST 2012


Have you guys explicitly laid out the documentation style conventions? I
was looking for something similar to
http://dev.mysql.com/doc/refman/5.5/en/manual-conventions.html but I
couldn't find it. When I asked about this on the IRC channel, I was
referred to 4.7 of the tutorial, which talks only briefly about
documentation and mostly related to source code documentation. I would
expect it to be discussed at http://docs.python.org/about.html.

The brackets [] around optional parameters is pretty standard, so even a
newbie like me understood it (altho I still think it should be disclosed),
but when I read http://docs.python.org/release/3.1.5/library/csv.html I
noticed that csv.reader has optional parameters which are not bracketed,
which confuses me a bit. I'm talking about *dialect='excel'*, ***fmtparams*.
I'm also not sure what ** means (I'm guessing multiple parameters?) or just
a single * means.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20121003/cf2803b7/attachment.html>


More information about the docs mailing list