Re: [Python-Dev] Best practice for documentation for std lib

On 9/22/2013 10:44 PM, Guido van Rossum wrote: On Sun, Sep 22, 2013 at 7:25 PM, Terry Reedy ('Return' rather than 'Returns' is the current convention.) That's actually a religious argument which in the stdlib takes no strict position -- a quick grep shows that both are used, although 'R

Re: [Python-Dev] Best practice for documentation for std lib

Am 23.09.2013 00:03, schrieb Guido van Rossum: > AFAIU, the proposal is to embed parts of the concise docstring into the > more > verbose .rst documentation. > > > I still think that's a bad idea. Someone editing the docstring may introduce a > terminology change or some other style/gra

Re: [Python-Dev] Best practice for documentation for std lib

On 23.09.13 17:18, Skip Montanaro wrote: It would be great if the docstring contained a link to the online documentation. That would have to be a feature of help(), not hardcoded in each docstring. That *is* a feature of the help function: Help on built-in module sys: help(sys) NAME

Re: [Python-Dev] Best practice for documentation for std lib

Given near-consensus on the "Return ..." form, the following discussion is of academic interest only. On Mon, Sep 23, 2013 at 9:31 PM, Steven D'Aprano wrote: > > I would not mind > > > > def foo(): > > """returns bar""" > > > > which I would read as "Function foo() returns bar," but in this

Re: [Python-Dev] Best practice for documentation for std lib

This is getting off-topic, if you're not interested in English grammar you should stop reading. On Mon, Sep 23, 2013 at 03:18:01PM -0400, Alexander Belopolsky wrote: > I don't think "Returns bar." is a valid English sentence because it lacks > subject. Subjectless sentences are unusual in Engl

Re: [Python-Dev] Best practice for documentation for std lib

On Mon, Sep 23, 2013 at 3:01 PM, Terry Reedy wrote: > 'Return' versus 'Returns', exact uppercase word match, is a little over 3 to > 1. I am sure I have seen 'Return' and similiar directive forms ('Print', > 'Store', 'Compare', etc) recommended as current doc style, as prefered by > the current do

Re: [Python-Dev] Best practice for documentation for std lib

On Mon, Sep 23, 2013 at 3:01 PM, Terry Reedy wrote: > > IIRC in the Java world you *have* to > >> use 'Returns', but I don't buy the argument from nit-picky grammarians >> that leads to this rule. (It's something about the documentation not >> being a command. But English is more flexible than th

Re: [Python-Dev] Best practice for documentation for std lib

On 23/09/2013 20:01, Terry Reedy wrote: On 9/22/2013 10:44 PM, Guido van Rossum wrote: Glad you like it. I still do, too, but I've given up hope to convince all core developers to stick to this style. :-( >[me] ('Return' rather than 'Returns' is the current convention.) That's actually a

Re: [Python-Dev] Best practice for documentation for std lib

On 9/22/2013 10:44 PM, Guido van Rossum wrote: Glad you like it. I still do, too, but I've given up hope to convince all core developers to stick to this style. :-( >[me] ('Return' rather than 'Returns' is the current convention.) That's actually a religious argument which in the stdlib tak

Re: [Python-Dev] Best practice for documentation for std lib

On Mon, Sep 23, 2013 at 10:52 AM, Terry Reedy wrote: > On 9/23/2013 10:56 AM, Guido van Rossum wrote: > > I think 60 is just a guideline. In stdlib .py source code I want it not >> to extend beyond the 79th column (see recent PEP 8 argument). For a >> > > PEP 8 says "Limit all lines to a maximum

Re: [Python-Dev] Best practice for documentation for std lib

On 9/23/2013 10:56 AM, Guido van Rossum wrote: I think 60 is just a guideline. In stdlib .py source code I want it not to extend beyond the 79th column (see recent PEP 8 argument). For a PEP 8 says "Limit all lines to a maximum of 79 characters. For flowing long blocks of text with fewer stru

Re: [Python-Dev] Best practice for documentation for std lib

On 9/23/2013 11:18 AM, Skip Montanaro wrote: It would be great if the docstring contained a link to the online documentation. That would have to be a feature of help(), not hardcoded in each docstring. That *is* a feature of the help function: Help on built-in module sys: help(sys) NAME

Re: [Python-Dev] Best practice for documentation for std lib

On 09/23/2013 04:43 PM, R. David Murray wrote: On Sun, 22 Sep 2013 16:19:21 -0700, Guido van Rossum wrote: On Sun, Sep 22, 2013 at 2:41 PM, Xavier Morel wrote: The points here are that there's a single source of truth (so we can't have conflicting docstring and rst documentation), and documen

Re: [Python-Dev] Best practice for documentation for std lib

>> It would be great if the docstring contained a link to the online >> documentation. > > That would have to be a feature of help(), not hardcoded in each docstring. That *is* a feature of the help function: Help on built-in module sys: >>> help(sys) NAME sys FILE (built-in) MODULE DO

Re: [Python-Dev] Best practice for documentation for std lib

On Mon, 23 Sep 2013 08:57:01 +0100 Larry Hastings wrote: > On 09/23/2013 03:44 AM, Guido van Rossum wrote: > > On Sun, Sep 22, 2013 at 7:25 PM, Terry Reedy > > wrote: > > > > I am gradually changing Idle docstrings, though only Idle > > developers will ever see th

Re: [Python-Dev] Best practice for documentation for std lib

On Sun, 22 Sep 2013 16:19:21 -0700, Guido van Rossum wrote: > On Sun, Sep 22, 2013 at 2:41 PM, Xavier Morel wrote: > > > The points here are that there's a single source of truth (so we can't > > have conflicting docstring and rst documentation), and documentation > > becoming outdated can be not

Re: [Python-Dev] Best practice for documentation for std lib

On Mon, Sep 23, 2013 at 12:57 AM, Larry Hastings wrote: > On 09/23/2013 03:44 AM, Guido van Rossum wrote: > > On Sun, Sep 22, 2013 at 7:25 PM, Terry Reedy wrote: > >> I am gradually changing Idle docstrings, though only Idle developers will >> ever see them. Writing a 60 char summary forces a

Re: [Python-Dev] Best practice for documentation for std lib

On Mon, Sep 23, 2013 at 4:27 AM, Walter Dörwald wrote: > It would be great if the docstring contained a link to the online > documentation. > That would have to be a feature of help(), not hardcoded in each docstring. -- --Guido van Rossum (python.org/~guido) ___

Re: [Python-Dev] Best practice for documentation for std lib

Le Mon, 23 Sep 2013 15:51:27 +0200, Walter Dörwald a écrit : > On 23.09.13 15:38, Fred Drake wrote: > > > On Mon, Sep 23, 2013 at 7:27 AM, Walter Dörwald > > wrote: > >> It would be great if the docstring contained a link to the online > >> documentation. > > > > The docstring itself, or the pre

Re: [Python-Dev] Best practice for documentation for std lib

On 23.09.13 15:38, Fred Drake wrote: On Mon, Sep 23, 2013 at 7:27 AM, Walter Dörwald wrote: It would be great if the docstring contained a link to the online documentation. The docstring itself, or the presentation generated by help() ? The presentation generated by help(), or the output o

Re: [Python-Dev] Best practice for documentation for std lib

On Mon, Sep 23, 2013 at 7:27 AM, Walter Dörwald wrote: > It would be great if the docstring contained a link to the online > documentation. The docstring itself, or the presentation generated by help() ? -Fred -- Fred L. Drake, Jr. "A storm broke loose in my mind." --Albert Einstein __

Re: [Python-Dev] Best practice for documentation for std lib

On 22.09.13 16:34, Brett Cannon wrote: 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

Re: [Python-Dev] Best practice for documentation for std lib

On 09/23/2013 03:44 AM, Guido van Rossum wrote: On Sun, Sep 22, 2013 at 7:25 PM, Terry Reedy > wrote: I am gradually changing Idle docstrings, though only Idle developers will ever see them. Writing a 60 char summary forces a clear understanding of the functi

Re: [Python-Dev] Best practice for documentation for std lib

Guido van Rossum writes: > On Sun, Sep 22, 2013 at 5:31 PM, Steven D'Aprano wrote: >> My own preference is to err on the side of too much rather than >> too little, since I live by help() and only fall back on the web >> documentation when I really must. > I guess preferences differ. Indee

Re: [Python-Dev] Best practice for documentation for std lib

On Sun, Sep 22, 2013 at 7:25 PM, Terry Reedy wrote: > On 9/22/2013 10:04 PM, Guido van Rossum wrote: > > If I had the final word, I'd recommend using the current docstrings as >> the .rst contents and replacing the docstrings with the 1-2 line >> function descriptions from the PEP, e.g.: >> >>

Re: [Python-Dev] Best practice for documentation for std lib

On 9/22/2013 10:04 PM, Guido van Rossum wrote: If I had the final word, I'd recommend using the current docstrings as the .rst contents and replacing the docstrings with the 1-2 line function descriptions from the PEP, e.g.: * median(data) -> median (middle value) of data, taking t

Re: [Python-Dev] Best practice for documentation for std lib

On Sun, Sep 22, 2013 at 5:31 PM, Steven D'Aprano wrote: > On Sun, Sep 22, 2013 at 10:07:28AM -0700, Guido van Rossum wrote: > > > Authors writing 3rd party packages can do what they want. > > > > But for the stdlib it's been settled for ages: docstrings should be > concise > > (but not cryptic(*))

Re: [Python-Dev] Best practice for documentation for std lib

On Sun, Sep 22, 2013 at 10:07:28AM -0700, Guido van Rossum wrote: > Authors writing 3rd party packages can do what they want. > > But for the stdlib it's been settled for ages: docstrings should be concise > (but not cryptic(*)), longer documentation go into the separately written > text for docs

Re: [Python-Dev] Best practice for documentation for std lib

On Sun, Sep 22, 2013 at 5:07 PM, Steven D'Aprano wrote: > If you're going to the source to read docstrings, you're doing it wrong > :-) > Be that as it may, when I'm reading the source I'm grateful for docstrings. *And* I'm grateful when they are short. -- --Guido van Rossum (python.org/~guido)

Re: [Python-Dev] Best practice for documentation for std lib

On Sun, Sep 22, 2013 at 05:54:57AM -0700, Eli Bendersky wrote: > IMHO the right way to think about it is that the .rst files are by far the > more important documentation. Sometimes we forget that most Python > programmers are people who won't go into the source to read docstrings. Docstrings are

Re: [Python-Dev] Best practice for documentation for std lib

On Sun, Sep 22, 2013 at 2:41 PM, Xavier Morel wrote: > The points here are that there's a single source of truth (so we can't > have conflicting docstring and rst documentation), and documentation > becoming outdated can be noticed from both docstring and published > documentation. > Another case

Re: [Python-Dev] Best practice for documentation for std lib

On Sun, Sep 22, 2013 at 11:44 AM, Eli Bendersky wrote: > > On Sun, Sep 22, 2013 at 11:40 AM, Guido van Rossum wrote: > >> On Sun, Sep 22, 2013 at 10:25 AM, Eli Bendersky wrote: >> >>> >>> I think there's a general agreement in this thread that we don't intend >>> to change the status quo. Both .

Re: [Python-Dev] Best practice for documentation for std lib

gt; Subject: Re: [Python-Dev] Best practice for documentation for std lib > > > On 2013-09-22, at 21:24 , Westley Martínez wrote: > > >> From: gvanros...@gmail.com [mailto:gvanros...@gmail.com] On Behalf Of Guido > >> van Rossum > >> Sent: Sunday, Septemb

Re: [Python-Dev] Best practice for documentation for std lib

On 2013-09-22, at 21:24 , Westley Martínez wrote: >> From: gvanros...@gmail.com [mailto:gvanros...@gmail.com] On Behalf Of Guido >> van Rossum >> Sent: Sunday, September 22, 2013 11:35 AM >> >> You seem to misunderstand the use of "autogeneration". It refers to >> generating >> the .rst docs fr

Re: [Python-Dev] Best practice for documentation for std lib

> From: gvanros...@gmail.com [mailto:gvanros...@gmail.com] On Behalf Of Guido > van Rossum > Sent: Sunday, September 22, 2013 11:35 AM > > You seem to misunderstand the use of "autogeneration". It refers to generating > the .rst docs from the docstrings in the source. And FWIW, I'm against that >

Re: [Python-Dev] Best practice for documentation for std lib

On Sun, Sep 22, 2013 at 11:40 AM, Guido van Rossum wrote: > On Sun, Sep 22, 2013 at 10:25 AM, Eli Bendersky wrote: > >> >> I think there's a general agreement in this thread that we don't intend >> to change the status quo. Both .rst docs and docstrings are important. The >> remaining question i

Re: [Python-Dev] Best practice for documentation for std lib

On Sun, Sep 22, 2013 at 10:25 AM, Eli Bendersky wrote: > > I think there's a general agreement in this thread that we don't intend to > change the status quo. Both .rst docs and docstrings are important. The > remaining question is - can we use some tool to generates parts of the > former from th

Re: [Python-Dev] Best practice for documentation for std lib

On Sun, Sep 22, 2013 at 11:02 AM, Westley Martínez wrote: > Since help() is usually the first thing I use to remind myself of an > API, it's imperative that the doc strings are up to date and make sense > to end users. > > So, autogeneration of doc strings would be good for someone like me who > h

Re: [Python-Dev] Best practice for documentation for std lib

- > From: Python-Dev [mailto:python-dev-bounces+anikom15=gmail@python.org] On > Behalf Of Brett Cannon > Sent: Sunday, September 22, 2013 7:34 AM > To: Steven D'Aprano > Cc: python-dev > Subject: Re: [Python-Dev] Best practice for documentation for std lib > > > >

Re: [Python-Dev] Best practice for documentation for std lib

On 9/22/2013 10:25 AM, Nick Coghlan wrote: As Georg noted, we'd have to do some fancy footwork to make sure autodoc didn't pick up the wrong module versions for the standard library docs, though. Is that a one-time nuisance, a per-module nuisance, a per-autodoc-use nuisance, or a per-build nu

Re: [Python-Dev] Best practice for documentation for std lib

On 09/22/2013 08:49 AM, Barry Warsaw wrote: On Sep 22, 2013, at 10:34 AM, Brett Cannon wrote: 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

Re: [Python-Dev] Best practice for documentation for std lib

On Sun, Sep 22, 2013 at 10:07 AM, Guido van Rossum wrote: > On Sun, Sep 22, 2013 at 9:53 AM, Stephen J. Turnbull > wrote: > >> Eli Bendersky writes: >> >> > IMHO the right way to think about it is that the .rst files are by >> > far the more important documentation. Sometimes we forget that >

Re: [Python-Dev] Best practice for documentation for std lib

On Sun, Sep 22, 2013 at 9:53 AM, Stephen J. Turnbull wrote: > Eli Bendersky writes: > > > IMHO the right way to think about it is that the .rst files are by > > far the more important documentation. Sometimes we forget that > > most Python programmers are people who won't go into the source >

Re: [Python-Dev] Best practice for documentation for std lib

Eli Bendersky writes: > IMHO the right way to think about it is that the .rst files are by > far the more important documentation. Sometimes we forget that > most Python programmers are people who won't go into the source Why "source"? The whole point of docstrings is that they are *not* com

Re: [Python-Dev] Best practice for documentation for std lib

On Sun, Sep 22, 2013 at 8:49 AM, Barry Warsaw wrote: > On Sep 22, 2013, at 10:34 AM, Brett Cannon wrote: > > >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 an

Re: [Python-Dev] Best practice for documentation for std lib

On Sep 22, 2013, at 10:34 AM, Brett Cannon wrote: >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.

Re: [Python-Dev] Best practice for documentation for std lib

> On 22 Sep 2013, at 05:25, Benjamin Peterson wrote: > > There's not really much to do but maintain them separately. Truncate > the docstrings if it makes life easier. Autodoc could be enabled and allowed in a limited manner. ___ Python-Dev mailing lis

Re: [Python-Dev] Best practice for documentation for std lib

On Sun, Sep 22, 2013 at 8:53 AM, Steven D'Aprano wrote: > On Sun, Sep 22, 2013 at 10:20:46AM +0200, Antoine Pitrou wrote: > > On Sun, 22 Sep 2013 13:13:04 +1000 > > Steven D'Aprano wrote: > > > Hi all, > > > > > > I have a question about how I should manage documentation for the > > > statistics

Re: [Python-Dev] Best practice for documentation for std lib

On 23 September 2013 00:16, Eli Bendersky wrote: > That's a good point. I would still posit that HTML documentation gets by far > the most use, but docstrings are definitely important too. One more point in > favor of either: > > 1. Maintaining both, as tiresome as it is (we try to do this, not al

Re: [Python-Dev] Best practice for documentation for std lib

On Sun, Sep 22, 2013 at 6:06 AM, Georg Brandl wrote: > On 09/22/2013 02:54 PM, Eli Bendersky wrote: > > > > > > > > On Sat, Sep 21, 2013 at 8:13 PM, Steven D'Aprano > > wrote: > > > > Hi all, > > > > I have a question about how I should manage documentation fo

Re: [Python-Dev] Best practice for documentation for std lib

On 22 September 2013 13:54, Eli Bendersky wrote: > IMHO the right way to think about it is that the .rst files are by far the > more important documentation. Sometimes we forget that most Python > programmers are people who won't go into the source to read docstrings. While I agree entirely with

Re: [Python-Dev] Best practice for documentation for std lib

On 09/22/2013 02:54 PM, Eli Bendersky wrote: > > > > On Sat, Sep 21, 2013 at 8:13 PM, Steven D'Aprano > wrote: > > Hi all, > > I have a question about how I should manage documentation for the > statistics module for Python 3.4. At the moment, I have ex

Re: [Python-Dev] Best practice for documentation for std lib

On Sat, Sep 21, 2013 at 8:13 PM, Steven D'Aprano wrote: > Hi all, > > I have a question about how I should manage documentation for the > statistics module for Python 3.4. At the moment, I have extensive > docstrings in the module itself. I don't believe anyone has flagged that > as "too much info

Re: [Python-Dev] Best practice for documentation for std lib

On Sun, Sep 22, 2013 at 10:20:46AM +0200, Antoine Pitrou wrote: > On Sun, 22 Sep 2013 13:13:04 +1000 > Steven D'Aprano wrote: > > Hi all, > > > > I have a question about how I should manage documentation for the > > statistics module for Python 3.4. At the moment, I have extensive > > docstring

Re: [Python-Dev] Best practice for documentation for std lib

On 09/22/2013 12:16 PM, Nick Coghlan wrote: > On 22 September 2013 18:54, Georg Brandl wrote: >> I don't really buy the argument "but then there is no complete documentation >> set in the checkout" -- who reads that in preference to docs.python.org? >> And if anybody does want plain-text docs, the

Re: [Python-Dev] Best practice for documentation for std lib

On 2013-09-22, at 12:16 , Nick Coghlan wrote: > > It's a bit of a pain, and we do occasionally get bug reports where the > docstrings get out of date, but it's the least bad of the currently > available options. Is it really less bad than allowing limited fine-grained use of autodoc? Not necessar

Re: [Python-Dev] Best practice for documentation for std lib

On 22 September 2013 18:54, Georg Brandl wrote: > I don't really buy the argument "but then there is no complete documentation > set in the checkout" -- who reads that in preference to docs.python.org? > And if anybody does want plain-text docs, they are already available for build > and for downl

Re: [Python-Dev] Best practice for documentation for std lib

On 09/22/2013 05:13 AM, Steven D'Aprano wrote: > Hi all, > > I have a question about how I should manage documentation for the > statistics module for Python 3.4. At the moment, I have extensive > docstrings in the module itself. I don't believe anyone has flagged that > as "too much informatio

Re: [Python-Dev] Best practice for documentation for std lib

On Sun, 22 Sep 2013 13:13:04 +1000 Steven D'Aprano wrote: > Hi all, > > I have a question about how I should manage documentation for the > statistics module for Python 3.4. At the moment, I have extensive > docstrings in the module itself. I don't believe anyone has flagged that > as "too muc

Re: [Python-Dev] Best practice for documentation for std lib

I don't like having to browse the source code to read the documentation. I prefer short docstring and longer reST documentation. In ReST, you get a table of content and nice links to functions, modules, etc. When I read doc, I like having two levels: tutorial listing most important functions and p

Re: [Python-Dev] Best practice for documentation for std lib

There's not really much to do but maintain them separately. Truncate the docstrings if it makes life easier. 2013/9/21 Steven D'Aprano : > Hi all, > > I have a question about how I should manage documentation for the > statistics module for Python 3.4. At the moment, I have extensive > docstrings

[Python-Dev] Best practice for documentation for std lib

Hi all, I have a question about how I should manage documentation for the statistics module for Python 3.4. At the moment, I have extensive docstrings in the module itself. I don't believe anyone has flagged that as "too much information" in a code review, so I'm going to assume that large doc