original) (raw)
(On Sun, Sep 22, 2013 at 8:49 AM, Barry Warsaw <barry@python.org> wrote:
On Sep 22, 2013, at 10:34 AM, Brett Cannon wrote:That's exactly my own rule of thumb too, so +1.
\>The rule of thumb I go by is the docstring should be enough to answer the
\>question "what args does this thing take and what does it do in general to
\>know it's the function I want and another one in the same module?" quickly
\>and succinctly; i.e. just enough so that help() reminds you about details
\>for a module you are already familiar with that might come up while at the
\>interpreter prompt. Everything else -- in-depth discussion of the
\>algorithms, extra examples, why you want to use this function, etc. -- all
\>go in the .rst docs.
It makes a lot of sense to me too. That said, I don't see a reason why we can't auto-generate the referenc-y stuff from docstrings into the .rst automatically, i.e.:
module.rst:
Algorithms, bla bla bla, examples bla bla bla
<ref:module.py Foo.bar>� # << Auto generator pastes function signature and docstring here
<ref:module.py Foo.bar>� # << Auto generator pastes function signature and docstring here
More algorithms, more bla bla, examples.
Eli
�