epydoc reST markup for stdlib docstrings

Hello Doc-Siggers,

During some recent work on the PEP 3147, I had a need to add some
documentation (docstrings) to some new functions.  To document the function
arguments I added epydoc reST style markup:

def ensure_bytecode_path(bytecode_path):
    """Ensure that the __pycache__ directory for PEP 3147 pyc file exists.

    :param bytecode_path: File system path to PEP 3147 pyc file.
    """

Now, I didn't even think twice about this because several of the larger Python
projects I work on have already adopted epydoc reST markup for API.  During
his review, Antoine disapproved of this, pointing to PEPs 257 and 287.  My
reading of these PEPs however, certainly doesn't prohibit the use of epydoc
reST markup.  Georg and I pointed to the lack of a clear, consistent convention
in the Python stdlib.  I would like to propose that epydoc reST markup be made
that convention.

http://epydoc.sourceforge.net/epydoc.html#epydoc-fields

PEP 257 does include an example for keyword arguments, but not much more is
said about them.  epydoc reST markup is compliant with PEP 287 IMO, by
adopting reST syntax.  I think Sphinx does a pretty good job of handling such
API markup too.

A PEP might be necessary to make this a firm decision.  What do you think
about adopting epydoc reST markup for documenting the stdlib API?

-Barry

_______________________________________________
Doc-SIG maillist  -  [email protected]
http://mail.python.org/mailman/listinfo/doc-sig

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.10 (GNU/Linux)

iQIcBAEBCAAGBQJLxN40AAoJEBJutWOnSwa/PvgQAJ4x1AtRQY2TEJNn5fZxo0ty
aM+IeNxnag8ARRcPElKqxtCNO1lHRdo60b4P5KHVymS+w8fzh7D8Wg0j5IZFHvzh
4LQWxS1XvlEhZ6JtmggfyauJD4rgd1/uRNyoacrNZhutNytKRvi5wmiiWfl0l7WQ
lAsxHyygTjhNR8Q+tF7fF9R8zwCnVsGndsY2tzRpw3vfCXLzekvXIZTMBWgqdWFm
HOj/d4Ie42M6tinRtZu6ZWW8patvOMPEoUEIFU582aMuVplXOlnl06zMUBMvAJJY
mB4aMZoK4EgkAxfS7w3UIBC6iuI9uu6nGZN1vFt48tZPiyxrK/Zwt0lM2nRI/UMK
4Melv6vxkyvi1duxcIMtbFuKg7CddIu2Q195wM7HWJrqUWca4tS9Mt8xyIqF/Vxu
WLI4dN30l3eXOH0TXBVjSsAhwOG+1uoi2rw/z90k6QDbJjbFZ8G+tX6I6X9SGi+2
cy7bcaAOH9rtCgGzsq+oHUDqel4TFjDM79Ymov3rZQH47nSICWOtqa5agSU311vO
gItFebaWybH5ga+xAMz+fkYY5OxHTksdH5MY3l+TJL3mF0FGr8kGKrywM8EYSRUW
8MyV8MCGVm7XktypvgnPA4mLz4fhegFWozwoeJ7//LI9LVjqC1CfT4LAceJp/sRr
1AaqzRk3aIhoKcOC8QEr
=7z0z
-----END PGP SIGNATURE-----