Re: epydoc reST markup for stdlib docstrings
Barry Warsaw <[email protected]>
| Newsgroups | gmane.comp.python.documentation |
|---|---|
| Organization | Damn Crazy Followers of the Horn |
| Message-ID | <20100414100755.6d321652@heresy> |
On Apr 14, 2010, at 11:58 PM, Nick Coghlan wrote: >Barry Warsaw wrote: >> On Apr 14, 2010, at 01:30 AM, Michael Foord wrote: >> >>> Definite +1 from me on adopting reST in docstrings as a standard. I >>> haven't looked at the Epydoc convention for parameters (etc) well enough >>> to have an opinion on that. >> >> The thing I like about them is that the rules are very simple, and once >> learned are easy to remember. > >Did you look at the NumPy guidelines Ralf posted?: >http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines > >Those look very clean to me, and fairly similar to what we already do in >the ReST docs. > >Because epydoc works with tags rather than sections, it looks a lot >"noisier" to me when reading the plain text version. And I'm not keen on the sections since I think they consume too much vertical whitespace. And I like the tags of epydoc format on the left side for their regularity. Everyone's got a different opinion, and the only one that matters is the BDFL's. :) OTOH, the specifics don't matter as much as just picking one for the stdlib. -Barry _______________________________________________ Doc-SIG maillist - [email protected] http://mail.python.org/mailman/listinfo/doc-sig
signature.asc
(application/pgp-signature, 836 B)
-----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.10 (GNU/Linux) iQIcBAEBCAAGBQJLxcw7AAoJEBJutWOnSwa/0jcP/2Tf9JOEHZ6veph9McFYViIU /y9nGED0o/eJJPh7FIBsAtAgL0Zc2eL3+E4EJhiP5Hh6S1m+zYLfB7e+Tok7Wd0G 7vrt0dYCdqwgtpnKKs+sn35WLKxceyRJz6A8eO9C/jlBPBNS7OVOzuIgpOloC+BS iagJTd7XS0+8QFHKztTCGMlAqQa36ueCSJiP4xD8fSgeBap0rdITMjcxL4jmiNSZ KrGiQiCwNVAvx0kt/TSfbEbSXpl39joGDWhmbq7y/qYJWuUv5ZdqsXgTm4nSAKkO GLxpZ4cBHefsb6WPhphh2yorC85N2mqBeOfU+Mz4EfYGRLWwtaD10Q/KgcYX5rz0 9VLmhCzhRuyE3nZFkVNRENUqAH+D67rAg6dHaa926X6LDXtiIcK+50mc6/RYKOeK Z/B/AVggbveOiC2Dt17tRUKo+zFZ18FFs6GP6xeDJaKBfHzbycS8H2QD3dK6zGBR Lw5wxn/vMOImjxYzD5/hLLRp8v1znoyq+dsjHeanhqsb9XQHQarJH9CvkVBy158M hrV/pyiXZCOdzhm8g55BGZjmZTTXbhCswIx7uuimUFwZrvx989DiU/S99HqS/JEp ziBuEeSPjaP5qK6nWos9S9Xfzl6yyOKkP7XMyuMoLE1F/RP+q8Av2TiJje7Zw3Dv vQDI++DIpvwXx8iuhZDG =GJls -----END PGP SIGNATURE-----