[Pulp-list] RST Docstrings

[Jay Dobies]

A while ago, I started using the RST format for docstrings (: instead of 
@ mostly) in any code that I expect to one day generate API docs for, 
the biggest example being for the plugin writers guides. I hate having 
two formats in the same codebase, but did it anyway despite my OCD.

 From the feedback I'm seeing, it sounds like the team as a whole wants 
to use this approach. So:

** Going forward, please use the RST docstrings instead of epydocs on 
all new methods. **

That said, in the interest of not making pull requests and diffs 
unbearable, *do not* start converting the code of modules you happen to 
be in for a different reason. If you're in a module to change one 
method, the pull request reviewer is going to hate life if there are a 
billion docstring updates to the other methods in the module.

Instead, as part of Mike's initiative to shuffle git around, I'm asking 
him to do that conversion as well. The git repo will already be frozen 
so he shouldn't hit conflicts and that part of the git history will 
already be annoying, so having those diffs in there won't be all that 
much worse.

Those of you using PyCharm, please configure in settings to use RST. 
That way when you start a docstring with """, it will auto populate the 
params/return with RST format instead of epydocs. It's under Settings -> 
Python Integrated Tools -> Docstring format of "reStructuredText"

Those of you not using PyCharm, seriously, get a real IDE.

Thoughts?

-- 
Jay Dobies
Freenode: jdob @ #pulp
http://pulpproject.org | http://blog.pulpproject.org