[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]

[Pulp-list] RST Docstrings



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


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]