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

[Victor Stinner]

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 parameters with examples, and a full API doc.

Using reST, you can also use tables, notes, footnotes, etc.

Victor
___
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] Revert #12085 fix for __del__ attribute error message

[Antoine Pitrou]

On Sat, 21 Sep 2013 19:55:05 -0400
Terry Reedy  wrote:
> 
> > In the general case it represents a bug in
> > the code that should be fixed.  Most such errors arise from the vagaries
> > of module finalization (such as your issue 19021),
> 
> Lets call that a buglet ;-). Not really harmful, but annoying.

It's not a buglet. A buggy __del__ method is as much a bug as any other
buggy method. __del__ issues can lead to resources not being properly
finalized and released to the system.

> Accepting 
> that even such buglets 'should' be fixed in the stdllib, so that the 
> message does not appear, is there any reason *not* to make it a 
> RuntimeWarning so that users who care about clean output can filter it 
> out while waiting for us to fix it?

Yes, the reason is that these are real exceptions, not warnings. The
reason the exceptions are not propagated is that they can occur at any
point (finalization is pretty much asynchronous, it can occur from
unrelated places), so propagating them to whatever code happens to
execute at the time would be a huge instability factor.

Making them warnings means they could be silenced depending on the
current warning settings.

Regards

Antoine.


___
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

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

[Antoine Pitrou]

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 much information" in a code review, so I'm going to assume that 
> large docstrings will be acceptable.

Related question: do the extensive docstrings make "help(stats)"
painful to browse through?

Regards

Antoine.


___
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] Revert #12085 fix for __del__ attribute error message

[Georg Brandl]

On 09/22/2013 10:19 AM, Antoine Pitrou wrote:
> On Sat, 21 Sep 2013 19:55:05 -0400
> Terry Reedy  wrote:
>> 
>> > In the general case it represents a bug in
>> > the code that should be fixed.  Most such errors arise from the vagaries
>> > of module finalization (such as your issue 19021),
>> 
>> Lets call that a buglet ;-). Not really harmful, but annoying.
> 
> It's not a buglet. A buggy __del__ method is as much a bug as any other
> buggy method. __del__ issues can lead to resources not being properly
> finalized and released to the system.
> 
>> Accepting 
>> that even such buglets 'should' be fixed in the stdllib, so that the 
>> message does not appear, is there any reason *not* to make it a 
>> RuntimeWarning so that users who care about clean output can filter it 
>> out while waiting for us to fix it?
> 
> Yes, the reason is that these are real exceptions, not warnings. The
> reason the exceptions are not propagated is that they can occur at any
> point (finalization is pretty much asynchronous, it can occur from
> unrelated places), so propagating them to whatever code happens to
> execute at the time would be a huge instability factor.
> 
> Making them warnings means they could be silenced depending on the
> current warning settings.

Which is not too bad, right?  (Assuming it's not silent by default.)

However, I'm not sure invoking the whole complicated warning filtering
and emitting code is what we want to do in a destructor...

Georg

___
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

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

[Georg Brandl]

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 information" in a code review, so I'm going to assume that 
> large docstrings will be acceptable.
> 
> However, I have been asked to ensure that there is a separate 
> statistics.rst file for documentation.
> 
> I don't want to have to maintain the documentation in two places, both 
> in the .py module and in .rst file. Can anyone give me some pointers as 
> to best practice in this situation? Is there a "How To Write Docs For 
> The Standard Library" document somewhere? Perhaps I missed it, but my 
> searches found nothing useful. I have read this:
> 
> http://docs.python.org/devguide/documenting.html
> 
> but it didn't shed any light on my situation.

This is the "How To Write etc." document.

If your docstrings really are complete, and marked up correctly, the new
module *could* be the first to use Sphinx autodoc for the stdlib documentation.
However, some core devs (including me) have stated opposition in the past.

The reason I myself have never really wanted to do this for the stdlib,
apart from most modules needing complete rewrites of their docstrings, is
that when documenting a standard module, you have to go through a few hoops
to make sure the build process actually imports the correct module to document,
and not the one of the Python version used to build the docs (which can
be different).

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 download anyway (reST processed by Sphinx to remove non-plain markup).

cheers,
Georg

___
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] Revert #12085 fix for __del__ attribute error message

[Antoine Pitrou]

On Sun, 22 Sep 2013 10:48:33 +0200
Georg Brandl  wrote:

> On 09/22/2013 10:19 AM, Antoine Pitrou wrote:
> > On Sat, 21 Sep 2013 19:55:05 -0400
> > Terry Reedy  wrote:
> >> 
> >> > In the general case it represents a bug in
> >> > the code that should be fixed.  Most such errors arise from the vagaries
> >> > of module finalization (such as your issue 19021),
> >> 
> >> Lets call that a buglet ;-). Not really harmful, but annoying.
> > 
> > It's not a buglet. A buggy __del__ method is as much a bug as any other
> > buggy method. __del__ issues can lead to resources not being properly
> > finalized and released to the system.
> > 
> >> Accepting 
> >> that even such buglets 'should' be fixed in the stdllib, so that the 
> >> message does not appear, is there any reason *not* to make it a 
> >> RuntimeWarning so that users who care about clean output can filter it 
> >> out while waiting for us to fix it?
> > 
> > Yes, the reason is that these are real exceptions, not warnings. The
> > reason the exceptions are not propagated is that they can occur at any
> > point (finalization is pretty much asynchronous, it can occur from
> > unrelated places), so propagating them to whatever code happens to
> > execute at the time would be a huge instability factor.
> > 
> > Making them warnings means they could be silenced depending on the
> > current warning settings.
> 
> Which is not too bad, right?  (Assuming it's not silent by default.)

The default is to print a given warning message only once, which isn't
the normal semantics of exceptions.

> However, I'm not sure invoking the whole complicated warning filtering
> and emitting code is what we want to do in a destructor...

Good point, too :-)

Regards

Antoine.


___
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

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

[Nick Coghlan]

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 download anyway (reST processed by Sphinx to remove non-plain markup).

This argument only applies to projects which have source and docs in
separate checkouts, which doesn't apply to CPython :)

As others have noted, the preferred approach is indeed to maintain the
prose docs independently of the docstrings. The latter are often
trimmed to just be a quick reminder of the details of how the function
works for those that already know, while the prose docs go into more
depth and have more examples.

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.

Cheers,
Nick.

-- 
Nick Coghlan   |   ncogh...@gmail.com   |   Brisbane, Australia
___
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

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

[Xavier Morel]

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 necessarily class-level and definitely not module-level, but
function- and method-level autodoc could allow avoiding duplication and
make it clearer that the prose and docstrings are getting out of sync.
___
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

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

[Georg Brandl]

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, they are already available for 
>> build
>> and for download anyway (reST processed by Sphinx to remove non-plain 
>> markup).
> 
> This argument only applies to projects which have source and docs in
> separate checkouts, which doesn't apply to CPython :)
> 
> As others have noted, the preferred approach is indeed to maintain the
> prose docs independently of the docstrings. The latter are often
> trimmed to just be a quick reminder of the details of how the function
> works for those that already know, while the prose docs go into more
> depth and have more examples.

That is the convincing argument, yes.

It could be argued that autodoc allows adding content in the rst file itself,
such as

.. autofunction:: mean

   

   Examples::

   >>> mean(life)
   "Try and be nice to people, avoid eating fat, read a good book ..."

But that means that when touching the docstring, one always has to look in
the rst file as well to check if the added content still makes sense.

cheers,
Georg

___
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

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

[Steven D'Aprano]

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 
> > 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 docstrings will be acceptable.
> 
> Related question: do the extensive docstrings make "help(stats)"
> painful to browse through?

Not to me. I can page through help(statistics) with 18 presses of the 
space bar, versus 20 for random or 45 for unittest. (29 lines per page.)

Admittedly statistics has fewer functions/classes than random, but I 
find that fewer, larger pieces of documentation are easier to read than 
lots of tiny one-line mentions that don't actually tell you anything. 
E.g. from unittest:

 |  Methods defined here:
 |
 |  __init__(self, stream, descriptions, verbosity)
 |
 |  addError(self, test, err)
 |
 |  addExpectedFailure(self, test, err)
 |
 |  addFailure(self, test, err)
 |
 |  addSkip(self, test, reason)

and so on for nearly a page. unittest is also packed with many, many 
one-line methods listed as deprecated.

I admit I'm a bit of a stats and maths junkie, I read stats text books 
for fun. So perhaps I'm not the best person to judge how much 
information is too much information. Comments to the tracker please:

http://bugs.python.org/issue18606



-- 
Steven
___
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

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

[Eli Bendersky]

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 information" in a code review, so I'm going to assume that
> large docstrings will be acceptable.
>
> However, I have been asked to ensure that there is a separate
> statistics.rst file for documentation.
>
> I don't want to have to maintain the documentation in two places, both
> in the .py module and in .rst file. Can anyone give me some pointers as
> to best practice in this situation? Is there a "How To Write Docs For
> The Standard Library" document somewhere? Perhaps I missed it, but my
> searches found nothing useful. I have read this:
>
> http://docs.python.org/devguide/documenting.html
>
> but it didn't shed any light on my situation.
>

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.
Moreover, the nice web layout, table of contents, index, and link-ability
of .rst is very important - I also prefer to read it as opposed to going
through docstrings. I only go to docstrings/code when I didn't find
something in the .rst docs, at this point also usually opening a bug to fix
that.

So whatever you do for statistics, full .rst docs must be there. It's the
docstrings that are "optional" here. The best solution may be auto
generating, for sure. But a module without .rst documented is unacceptable.

Eli
___
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

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

[Georg Brandl]

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 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 docstrings will be acceptable.
> 
> However, I have been asked to ensure that there is a separate
> statistics.rst file for documentation.
> 
> I don't want to have to maintain the documentation in two places, both
> in the .py module and in .rst file. Can anyone give me some pointers as
> to best practice in this situation? Is there a "How To Write Docs For
> The Standard Library" document somewhere? Perhaps I missed it, but my
> searches found nothing useful. I have read this:
> 
> http://docs.python.org/devguide/documenting.html
> 
> but it didn't shed any light on my situation.
> 
> 
> 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. Moreover, the nice web
> layout, table of contents, index, and link-ability of .rst is very important 
> - I
> also prefer to read it as opposed to going through docstrings.

Note -- using autodoc gives you this.

> I only go to docstrings/code when I didn't find something in the .rst docs, 
> at 
> this point also usually opening a bug to fix that.
> So whatever you do for statistics, full .rst docs must be there.

I guess you don't mean .rst here; you mean .html (or .pdf, etc), whatever the
toolchain outputs.

cheers,
Georg

___
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

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

[Paul Moore]

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 this, it's worth noting that with the
increasing popularity of IPython (even outside of the scientific
community), more and more people are becoming used to using docstrings
as a first means of finding out about a function's behaviour.

Paul
___
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

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

[Eli Bendersky]

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 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 docstrings will be acceptable.
> >
> > However, I have been asked to ensure that there is a separate
> > statistics.rst file for documentation.
> >
> > I don't want to have to maintain the documentation in two places,
> both
> > in the .py module and in .rst file. Can anyone give me some pointers
> as
> > to best practice in this situation? Is there a "How To Write Docs For
> > The Standard Library" document somewhere? Perhaps I missed it, but my
> > searches found nothing useful. I have read this:
> >
> > http://docs.python.org/devguide/documenting.html
> >
> > but it didn't shed any light on my situation.
> >
> >
> > 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. Moreover, the
> nice web
> > layout, table of contents, index, and link-ability of .rst is very
> important - I
> > also prefer to read it as opposed to going through docstrings.
>
> Note -- using autodoc gives you this.
>
> > I only go to docstrings/code when I didn't find something in the .rst
> docs, at
> > this point also usually opening a bug to fix that.
> > So whatever you do for statistics, full .rst docs must be there.
>
> I guess you don't mean .rst here; you mean .html (or .pdf, etc), whatever
> the
> toolchain outputs.
>

Yes, by .rst docs I mean the final HTML output, not the .rst files
themselves :-)

 Paul Moore:
>While I agree entirely with this, it's worth noting that with the
increasing popularity of IPython (even outside of the scientific
community), more and more people are becoming used to using docstrings
as a first means of finding out about a function's behaviour.
--

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 always
successfully, for all stdlib modules).
2. autodoc

Eli
___
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

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

[Nick Coghlan]

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 always
> successfully, for all stdlib modules).
> 2. autodoc

FWIW, I've generally found *tactical* use of autodoc (i.e. function
and method level usage for cases where the docstrings and prose docs
*were* the same) to be quite effective. Then if there later proved to
value in splitting them for a given case, that's what I would do. It
isn't an all-or-nothing decision.

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.

Cheers,
Nick.

-- 
Nick Coghlan   |   ncogh...@gmail.com   |   Brisbane, Australia
___
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

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

[Brett Cannon]

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 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 docstrings will be acceptable.
> >
> > Related question: do the extensive docstrings make "help(stats)"
> > painful to browse through?
>
> Not to me. I can page through help(statistics) with 18 presses of the
> space bar, versus 20 for random or 45 for unittest. (29 lines per page.)
>
> Admittedly statistics has fewer functions/classes than random, but I
> find that fewer, larger pieces of documentation are easier to read than
> lots of tiny one-line mentions that don't actually tell you anything.
> E.g. from unittest:
>
>  |  Methods defined here:
>  |
>  |  __init__(self, stream, descriptions, verbosity)
>  |
>  |  addError(self, test, err)
>  |
>  |  addExpectedFailure(self, test, err)
>  |
>  |  addFailure(self, test, err)
>  |
>  |  addSkip(self, test, reason)
>
> and so on for nearly a page. unittest is also packed with many, many
> one-line methods listed as deprecated.
>
> I admit I'm a bit of a stats and maths junkie, I read stats text books
> for fun. So perhaps I'm not the best person to judge how much
> information is too much information. Comments to the tracker please:
>
> http://bugs.python.org/issue18606


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.
___
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

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

[Xavier Morel]

> 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 list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

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

[Barry Warsaw]

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. 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.

That's exactly my own rule of thumb too, so +1.

-Barry
___
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

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

[Eli Bendersky]

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 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.
>
> That's exactly my own rule of thumb too, so +1.
>

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

  # << Auto generator pastes function signature and
docstring here

More algorithms, more bla bla, examples.

Eli
___
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

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

[Stephen J. Turnbull]

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*
comments found only in the source, but available at run time. In fact,
programmers who also use environments like Lisp or R (not to forget
Idle) will reach for "help(mean)", and that works fine for Steven,
because he provides such nice docstrings.

Some people prefer to write separate manuals, and some modules
*should* be documented that way because their internal complexity or
whatever.  That's true, but I would hope authors who prefer "literate
programming" (or the poor man's lit prog that is writing only
docstrings) are encouraged to do so when appropriate.

Of course, like any other contribution, since that style is *not*
currently supported by python-dev, they'd be asked to step up and
support it themselves -- if a user reports the docs won't build, they
need to address that like they would a build bug in the code.
___
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

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

[Guido van Rossum]

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
>
> Why "source"?  The whole point of docstrings is that they are *not*
> comments found only in the source, but available at run time. In fact,
> programmers who also use environments like Lisp or R (not to forget
> Idle) will reach for "help(mean)", and that works fine for Steven,
> because he provides such nice docstrings.
>
> Some people prefer to write separate manuals, and some modules
> *should* be documented that way because their internal complexity or
> whatever.  That's true, but I would hope authors who prefer "literate
> programming" (or the poor man's lit prog that is writing only
> docstrings) are encouraged to do so when appropriate.
>
> Of course, like any other contribution, since that style is *not*
> currently supported by python-dev, they'd be asked to step up and
> support it themselves -- if a user reports the docs won't build, they
> need to address that like they would a build bug in the code.


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.python.org.

(*) This is too concise to my taste:
$ ls -?
ls: illegal option -- ?
usage: ls [-ABCFGHLOPRSTUWabcdefghiklmnopqrstuwx1] [file ...]
$


-- 
--Guido van Rossum (python.org/~guido)
___
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

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

[Eli Bendersky]

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
>>  > most Python programmers are people who won't go into the source
>>
>> Why "source"?  The whole point of docstrings is that they are *not*
>> comments found only in the source, but available at run time. In fact,
>> programmers who also use environments like Lisp or R (not to forget
>> Idle) will reach for "help(mean)", and that works fine for Steven,
>> because he provides such nice docstrings.
>>
>> Some people prefer to write separate manuals, and some modules
>> *should* be documented that way because their internal complexity or
>> whatever.  That's true, but I would hope authors who prefer "literate
>> programming" (or the poor man's lit prog that is writing only
>> docstrings) are encouraged to do so when appropriate.
>>
>> Of course, like any other contribution, since that style is *not*
>> currently supported by python-dev, they'd be asked to step up and
>> support it themselves -- if a user reports the docs won't build, they
>> need to address that like they would a build bug in the code.
>
>
> 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.python.org.
>

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 the latter and thus avoid duplication and rot?

Eli
___
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

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

[Ethan Furman]

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 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.


That's exactly my own rule of thumb too, so +1.


Another +1.  So it that three rules or three thumbs?  ;)

--
~Ethan~
___
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] Revert #12085 fix for __del__ attribute error message

[Terry Reedy]

On 9/21/2013 10:30 PM, Guido van Rossum wrote:

Exceptions in __del__ point to bugs (sometimes in the stdlib) that
should be fixed, period. The only reason they do not result in
exceptions that are properly bubbled up and catchable is because __del__
is called from a DECREF macro which has no return value.


That is clear enough. What fooled me is the word 'ignored', in both the 
doc and message. How about 'skipped' (for technical reasons)?



Also, IMO
writing to stderr is fair game -- reporting errors is what it is for.


So developers who really want to control all screen output should 
redirect or capture it somehow.



As to making them warnings, I don't know that the warnings machinery is
easily adaptable for this purpose. Warnings can be suppressed but they
can also be turned into full exceptions; the latter doesn't really apply
here (see previous paragraph). But I would not object if someone found a
way to do this, though I'd prefer the default behavior to remain what it
is in 3.4 (print a full traceback).


Antoine and Georg think it a dubious idea, so I will not pursue it. 
Developers who encounter messages from the stdlib can report and wait 
for a fix.


--
Terry Jan Reedy

___
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

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

[Terry Reedy]

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 nuisance?


--
Terry Jan Reedy

___
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

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

[Westley Martínez]

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
hardly uses the html docs.

> -Original Message-
> 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
> 
> 
> 
> 
> 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 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 docstrings will be acceptable.
>   >
>   > Related question: do the extensive docstrings make "help(stats)"
>   > painful to browse through?
> 
> 
>   Not to me. I can page through help(statistics) with 18 presses of the
>   space bar, versus 20 for random or 45 for unittest. (29 lines per page.)
> 
>   Admittedly statistics has fewer functions/classes than random, but I
>   find that fewer, larger pieces of documentation are easier to read than
>   lots of tiny one-line mentions that don't actually tell you anything.
>   E.g. from unittest:
> 
>|  Methods defined here:
>|
>|  __init__(self, stream, descriptions, verbosity)
>|
>|  addError(self, test, err)
>|
>|  addExpectedFailure(self, test, err)
>|
>|  addFailure(self, test, err)
>|
>|  addSkip(self, test, reason)
> 
>   and so on for nearly a page. unittest is also packed with many, many
>   one-line methods listed as deprecated.
> 
>   I admit I'm a bit of a stats and maths junkie, I read stats text books
>   for fun. So perhaps I'm not the best person to judge how much
>   information is too much information. Comments to the tracker please:
> 
>   http://bugs.python.org/issue18606
> 
> 
> 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.

___
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

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

[Guido van Rossum]

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
> hardly uses the html docs.
>

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 practice.

-- 
--Guido van Rossum (python.org/~guido)
___
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

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

[Guido van Rossum]

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 the latter and thus avoid duplication and rot?
>

I don't think that duplication is much of an issue. Natural language
understanding is not at the level yet where you can generate a meaningful
summary from a longer text fully automatically (let alone vice versa :-) so
I think having to write both a concise docstring and a longer more detailed
description for the Doc tree is not a waste of effort at all.

As for rot, it's just as likely that rot occurs as a *result* of
autogeneration. Having to edit/patch the source code in order to improve
the documentation most likely adds an extra barrier towards improving the
docs.

-- 
--Guido van Rossum (python.org/~guido)
___
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] Revert #12085 fix for __del__ attribute error message

[Guido van Rossum]

On Sun, Sep 22, 2013 at 10:35 AM, Terry Reedy  wrote:

> On 9/21/2013 10:30 PM, Guido van Rossum wrote:
>
>> Exceptions in __del__ point to bugs (sometimes in the stdlib) that
>> should be fixed, period. The only reason they do not result in
>> exceptions that are properly bubbled up and catchable is because __del__
>> is called from a DECREF macro which has no return value.
>>
>
> That is clear enough. What fooled me is the word 'ignored', in both the
> doc and message. How about 'skipped' (for technical reasons)?


That's a good point, although I'm not sure 'skipped' is better. Maybe use a
more neutral verb like 'occurred'?

-- 
--Guido van Rossum (python.org/~guido)
___
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

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

[Eli Bendersky]

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 is - can we use some tool to generates parts of the
>> former from the latter and thus avoid duplication and rot?
>>
>
> I don't think that duplication is much of an issue. Natural language
> understanding is not at the level yet where you can generate a meaningful
> summary from a longer text fully automatically (let alone vice versa :-) so
> I think having to write both a concise docstring and a longer more detailed
> description for the Doc tree is not a waste of effort at all.
>

I don't think the proposal is to generate summaries from a longer text.
AFAIU, the proposal is to embed parts of the concise docstring into the
more verbose .rst documentation.

I write .rst docs quite a lot, and as such I do notice the annoying amount
of duplication between docstrings and .rst docs. Without doubt, all the
free-flow text and examples in .rst have to be written manually and are
very important. But for dry method references, it's certainly interesting
to explore the idea of writing them once in the code and then having Sphinx
automatically insert the relevant parts into the .rst before generating
HTML from it. For end users (those who read the docs online) the result is
indistinguishable from what we have now. For us devs it means writing the
same text only once and maintaining it in a single place.

Think about the new statistics module as a guinea pig. Steven will have a
whole lot of copy-pasting to do :-)


>
> As for rot, it's just as likely that rot occurs as a *result* of
> autogeneration. Having to edit/patch the source code in order to improve
> the documentation most likely adds an extra barrier towards improving the
> docs.
>

This is a valid concern, but perhaps one that can be addressed separately?
(i.e. lowering that barrier of entry).

Eli
___
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

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

[Westley Martínez]

> 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
> practice. 

Oh I see.  Well in that case, the docstrings can still become outdated,
and so then the .rst docs will be outdated, too.  It doesn't seem to
offer much benefit since you still have to keep both updated, plus you
have an extra tool that must be maintained.

___
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] Revert #12085 fix for __del__ attribute error message

[Terry Reedy]

On 9/22/2013 2:41 PM, Guido van Rossum wrote:

On Sun, Sep 22, 2013 at 10:35 AM, Terry Reedy mailto:tjre...@udel.edu>> wrote:

On 9/21/2013 10:30 PM, Guido van Rossum wrote:

Exceptions in __del__ point to bugs (sometimes in the stdlib) that
should be fixed, period. The only reason they do not result in
exceptions that are properly bubbled up and catchable is because
__del__
is called from a DECREF macro which has no return value.


That is clear enough. What fooled me is the word 'ignored', in both
the doc and message. How about 'skipped' (for technical reasons)?


That's a good point, although I'm not sure 'skipped' is better.


Only slightly ;-). The problem with both words is that they try to say 
two things. What happened, and what Python did about it.



Maybe use a more neutral verb like 'occurred'?


"Exception occurred in ..." is even better at say what happened.

I think we should then add an explict statement as to what Python did, 
and hint at what the user should do, something like

"Although caught internally, it still indicates a problem."

Otherwise, when no other output follows, as in
...
> del c
Exception ocurred in: ", line 2, in __del__
AttributeError:
>>>
It may not be completely obvious to a non-expert that the traceback is 
not a 'real' traceback from an exception that was allowed to propagate, 
and that it did not stop execution and cannot be caught.


--
Terry Jan Reedy

___
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

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

[Xavier Morel]

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 from the docstrings in the source. And FWIW, I'm against that
>> practice. 
> 
> Oh I see.  Well in that case, the docstrings can still become outdated,
> and so then the .rst docs will be outdated, too.

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.

>  It doesn't seem to
> offer much benefit since you still have to keep both updated, plus you
> have an extra tool that must be maintained.

There is no extra tool, autodoc is part of the standard Sphinx
distribution: http://sphinx-doc.org/ext/autodoc.html
___
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

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

[Westley Martínez]

Well, I'm wholly confused now, so I'll leave this discussion to the
devs.

> -Original Message-
> From: Python-Dev [mailto:python-dev-bounces+anikom15=gmail@python.org] On
> Behalf Of Xavier Morel
> Sent: Sunday, September 22, 2013 2:42 PM
> To: python-dev
> 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, 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
> >> practice.
> >
> > Oh I see.  Well in that case, the docstrings can still become outdated,
> > and so then the .rst docs will be outdated, too.
> 
> 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.
> 
> >  It doesn't seem to
> > offer much benefit since you still have to keep both updated, plus you
> > have an extra tool that must be maintained.
> 
> There is no extra tool, autodoc is part of the standard Sphinx
> distribution: http://sphinx-doc.org/ext/autodoc.html
> ___
> Python-Dev mailing list
> Python-Dev@python.org
> https://mail.python.org/mailman/listinfo/python-dev
> Unsubscribe: https://mail.python.org/mailman/options/python-
> dev/anikom15%40gmail.com

___
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

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

[Guido van Rossum]

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 .rst docs and docstrings are important. The
>>> remaining question is - can we use some tool to generates parts of the
>>> former from the latter and thus avoid duplication and rot?
>>>
>>
>> I don't think that duplication is much of an issue. Natural language
>> understanding is not at the level yet where you can generate a meaningful
>> summary from a longer text fully automatically (let alone vice versa :-) so
>> I think having to write both a concise docstring and a longer more detailed
>> description for the Doc tree is not a waste of effort at all.
>>
>
> I don't think the proposal is to generate summaries from a longer text.
>

I know, I was being facetious. :-)


> 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/grammar/flow change that
makes perfectly sense by itself but doesn't when taken in the context of
the larger .rst doc (e.g. it could introducing duplication or cause
dissonance between the two parts). Also, someone who wants to improve the
docs would have to figure out how to edit the source code if they wanted to
change some part of the docs.


> I write .rst docs quite a lot, and as such I do notice the annoying amount
> of duplication between docstrings and .rst docs. Without doubt, all the
> free-flow text and examples in .rst have to be written manually and are
> very important. But for dry method references, it's certainly interesting
> to explore the idea of writing them once in the code and then having Sphinx
> automatically insert the relevant parts into the .rst before generating
> HTML from it. For end users (those who read the docs online) the result is
> indistinguishable from what we have now. For us devs it means writing the
> same text only once and maintaining it in a single place.
>

You seem to have caught the DRY bug. But it doesn't always make sense to
factor things so that everything is said in exactly one place. (For an
example of abstraction gone wild, ironically, see docutils and sphinx. I
challenge you to find out the actual code that translates e.g.
:meth:`foobar` into foobar. :-)


> Think about the new statistics module as a guinea pig. Steven will have a
> whole lot of copy-pasting to do :-)
>

The docstrings should probably be limited to the amount of text that's
currently devoted to each function in the PEP. What's currently in the
docstrings should go into the .rst docs.


> > As for rot, it's just as likely that rot occurs as a *result* of
> autogeneration.
>
> Having to edit/patch the source code in order to improve the
> > documentation most likely adds an extra barrier towards improving the
> docs.
>
> This is a valid concern, but perhaps one that can be addressed separately?
> (i.e. lowering that barrier of entry).
>

I can't see that there's any way to interpret the change you propose
(changing things so that in order to improve the HTML docs you might need
to edit both .rst and .py files) as lowering the barrier to entry. Please
give it up.

-- 
--Guido van Rossum (python.org/~guido)
___
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

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

[Guido van Rossum]

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 of DRY madness.

It seems too many programmers see documentation as unpleasant red tape they
want to cut through as quickly as possible, instead of an opportunity to
communicate with their *users*. To the contrary: users should be the most
important people in the world if you're writing code that's worth
documenting at all.

-- 
--Guido van Rossum (python.org/~guido)
___
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

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

[Steven D'Aprano]

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 never more than one command away in the interactive 
interpreter:

help(some.function)


If you're going to the source to read docstrings, you're doing it wrong
:-)

I always go for interactive help first, and the web docs second. The 
only reason I go to the source is to read the source *code*, not the 
docstrings.



-- 
Steven
___
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

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

[Guido van Rossum]

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)
___
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

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

[Steven D'Aprano]

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.python.org.

It is the second half that I'm not sure about. How long is *too long*
for a doc string? 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.

Rather than keep talking in generalities, I'll come up with a first 
draft rst document over the next week or so, put it on the tracker, and 
wait for some concrete feedback on that.

What's the policy about linking to external content from the web docs?



-- 
Steven
___
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

[Python-Dev] Enum Eccentricities

[Ethan Furman]

http://bugs.python.org/issue19011

So, as anyone who has worked with Enum is probably aware by now, Enum's are a strange duck -- you might even call them 
platypuses.


For example, Enum members are instances of the class, but they are defined inside the class structure, and new ones 
cannot be created afterwards; Enum classes also support iteration and containment checks.


What I'm looking for feedback on is the question is #19011: should an Enum 
member be considered a class level attribute?

On the one hand, they are defined inside the class, and they are accessed via 
dot notation (EnumClass.member).

On the other hand, inside the class they look like 3 and 5 and 'up' and 'east', 
and they don't live in the class dictionary.

Also, if we change Enum so that members do act more like class attributes, then things like Color.red.blue.green.blue 
will result in Color.blue, and that seems stranger to me than having class instances be available on the class without 
be full-fledged class-attributes.


Thoughts?  Opinions?  Pearls of wisdom?

--
~Ethan~
___
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] PEP 455: TransformDict

[Ethan Furman]

On 09/14/2013 12:31 PM, Guido van Rossum wrote:

On Fri, Sep 13, 2013 at 11:40 AM, Antoine Pitrou wrote:


Following the python-dev discussion, I've written a PEP to recap the
proposal and the various arguments. It's inlined below, and it will
probably appear soon at http://www.python.org/dev/peps/pep-0455/, too.


Thanks, Antoine!

Raymond Hettinger has volunteered to be the PEP dictator (is that the word we 
use?) for this PEP.


Are we close to asking for pronouncement?  I haven't seen any chatter for a few 
days.

--
~Ethan~
___
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

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

[Guido van Rossum]

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(*)), longer documentation go into the separately written
> > text for docs.python.org.
>
> It is the second half that I'm not sure about. How long is *too long*
> for a doc string? 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. I like reading the source, and often I find
overly long docstrings distracting.

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 the
  average of the two middle values when there are an even
  number of values.

But omitting the signature proper, and replacing "->" with "Returns" or
"Returns the". E.g.

def median(data):
"""Returns the median (middle value) of data, taking the
   average of the two middle values when there are an even
   number of values.
"""
...

I'd personally also rewrite them all so that the first line of the
docstring is a phrase that can stand by itself, as I describe in PEP 8, but
this is used only sporadically in the stdlib.


> Rather than keep talking in generalities, I'll come up with a first
> draft rst document over the next week or so, put it on the tracker, and
> wait for some concrete feedback on that.
>
> What's the policy about linking to external content from the web docs?
>

If it's for background information or an introduction to the theory that's
fine. If it's as a substitute for proper documentation of an API I'd frown
upon it. Someone in a spaceship on its way to Mars  with a copy of
docs.python.org should have no problems using the library, as long as they
are familiar with the basic theory such as might be explained on Wikipedia
(of which the spaceship would of course also have a copy :-).

-- 
--Guido van Rossum (python.org/~guido)
___
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

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

[Terry Reedy]

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 the
   average of the two middle values when there are an even
   number of values.

But omitting the signature proper, and replacing "->" with "Returns" or
"Returns the". E.g.

 def median(data):
 """Returns the median (middle value) of data, taking the
average of the two middle values when there are an even
number of values.
 """
 ...

I'd personally also rewrite them all so that the first line of the
docstring is a phrase that can stand by itself, as I describe in PEP 8,
but this is used only sporadically in the stdlib.


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 function. Applied to the above.


  def median(data):
  """Return the median (middle value) of data.

  Use the average of the two middle values when
  there are an even number of values.
  """
('Return' rather than 'Returns' is the current convention.)

--
Terry Jan Reedy

___
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] Enum Eccentricities

[Guido van Rossum]

On Sun, Sep 22, 2013 at 4:52 PM, Ethan Furman  wrote:

> http://bugs.python.org/**issue19011 
>
> So, as anyone who has worked with Enum is probably aware by now, Enum's
> are a strange duck -- you might even call them platypuses.
>
> For example, Enum members are instances of the class, but they are defined
> inside the class structure, and new ones cannot be created afterwards; Enum
> classes also support iteration and containment checks.
>
> What I'm looking for feedback on is the question is #19011: should an Enum
> member be considered a class level attribute?
>
> On the one hand, they are defined inside the class, and they are accessed
> via dot notation (EnumClass.member).
>
> On the other hand, inside the class they look like 3 and 5 and 'up' and
> 'east', and they don't live in the class dictionary.
>
> Also, if we change Enum so that members do act more like class attributes,
> then things like Color.red.blue.green.blue will result in Color.blue, and
> that seems stranger to me than having class instances be available on the
> class without be full-fledged class-attributes.
>
> Thoughts?  Opinions?  Pearls of wisdom?
>

I wouldn't lose much sleep over this. Classes can override __getattribute__
so that instance variables appear to exist even though they are not in the
instance's __dict__. It's the same for metaclasses.

As for attributes appearing different inside the class than when accessed
as an attribute, that's not unusual -- descriptors can legitimately do
that. It was more common in Python 2, where this applied to all unbound
methods, but even in Python 3 it applies to static and class methods.

I would draw the line at being able to access members as attributes of
other members. Making Color.red.blue be a spelling for Color.blue feels
like an abomination. If you can make dir(Color) return the strings 'red',
'blue' etc. in addition to other class attributes without making
Color.red.blue work, go for it. If you can't, that's fine too. Users should
(obviously) steer clear from relying on either behavior.

-- 
--Guido van Rossum (python.org/~guido)
___
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

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

[Guido van Rossum]

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.:
>>
>>  * median(data) -> median (middle value) of data, taking the
>>average of the two middle values when there are an even
>>number of values.
>>
>> But omitting the signature proper, and replacing "->" with "Returns" or
>> "Returns the". E.g.
>>
>>  def median(data):
>>  """Returns the median (middle value) of data, taking the
>> average of the two middle values when there are an even
>> number of values.
>>  """
>>  ...
>>
>> I'd personally also rewrite them all so that the first line of the
>> docstring is a phrase that can stand by itself, as I describe in PEP 8,
>> but this is used only sporadically in the stdlib.
>>
>
> 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 function. Applied to the above.
>
>   def median(data):
>   """Return the median (middle value) of data.
>
>   Use the average of the two middle values when
>
>   there are an even number of values.
>   """
>

Glad you like it. I still do, too, but I've given up hope to convince all
core developers to stick to this style. :-(


>  ('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 'Return' is
more frequent by a 5-to-1 margin. 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 that.)

-- 
--Guido van Rossum (python.org/~guido)
___
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] Enum Eccentricities

[Greg Ewing]

Ethan Furman wrote:
Also, if we change Enum so that members do act more like class 
attributes, then things like Color.red.blue.green.blue will result in 
Color.blue,


I thought we already decided it was worth making that
not happen?

--
Greg
___
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] Revert #12085 fix for __del__ attribute error message

[Nick Coghlan]

On 23 Sep 2013 06:38, "Terry Reedy"  wrote:
>
> On 9/22/2013 2:41 PM, Guido van Rossum wrote:
>>
>> On Sun, Sep 22, 2013 at 10:35 AM, Terry Reedy > > wrote:
>>
>> On 9/21/2013 10:30 PM, Guido van Rossum wrote:
>>
>> Exceptions in __del__ point to bugs (sometimes in the stdlib)
that
>> should be fixed, period. The only reason they do not result in
>> exceptions that are properly bubbled up and catchable is because
>> __del__
>> is called from a DECREF macro which has no return value.
>>
>>
>> That is clear enough. What fooled me is the word 'ignored', in both
>> the doc and message. How about 'skipped' (for technical reasons)?
>>
>>
>> That's a good point, although I'm not sure 'skipped' is better.
>
>
> Only slightly ;-). The problem with both words is that they try to say
two things. What happened, and what Python did about it.
>
>
>> Maybe use a more neutral verb like 'occurred'?
>
>
> "Exception occurred in ..." is even better at say what happened.
>
> I think we should then add an explict statement as to what Python did,
and hint at what the user should do, something like
> "Although caught internally, it still indicates a problem."

Brevity is still a virtue. The relevant C API function is called
"PyErr_WriteUnraisable", so just starting the message as something like
"Unraisable exception suppressed in..." might work.

Cheers,
Nick.

>
> Otherwise, when no other output follows, as in
> ...
> > del c
> Exception ocurred in: 
> Traceback (most recent call last):
>   File "", line 2, in __del__
> AttributeError:
> >>>
> It may not be completely obvious to a non-expert that the traceback is
not a 'real' traceback from an exception that was allowed to propagate, and
that it did not stop execution and cannot be caught.
>
>
> --
> Terry Jan Reedy
>
> ___
> Python-Dev mailing list
> Python-Dev@python.org
> https://mail.python.org/mailman/listinfo/python-dev
> Unsubscribe:
https://mail.python.org/mailman/options/python-dev/ncoghlan%40gmail.com
___
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] Enum Eccentricities

[Zero Piraeus]

:

On Sun, Sep 22, 2013 at 04:52:36PM -0700, Ethan Furman wrote:
> So, as anyone who has worked with Enum is probably aware by now,
> Enum's are a strange duck -- you might even call them platypuses.

Yes :-)

> What I'm looking for feedback on is the question is #19011: should an
> Enum member be considered a class level attribute?

I may be misunderstanding the use case given in the issue, but it seems
to me that having to use

Color.red.__class__.blue

(what is being complained about in the issue), while not exactly pretty,
makes a lot more semantic sense than

Color.red.blue

... which is just bizarre.

Enum members aren't class attributes, even if the way they're defined
makes them look as though they are. Allowing this is just asking for
more confusion on the part of anyone using them IMHO.

 -[]z.

-- 
Zero Piraeus: omnia omnibus
http://etiol.net/pubkey.asc
___
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] Revert #12085 fix for __del__ attribute error message

[Guido van Rossum]

On Sunday, September 22, 2013, Nick Coghlan wrote:
>
> Brevity is still a virtue. The relevant C API function is called
> "PyErr_WriteUnraisable", so just starting the message as something like
> "Unraisable exception suppressed in..." might work.
>

Somehow "unraisable" sounds too technical, and "suppressed" is hardly right
given that it is printed...

Let's leave well enough alone.

--Guido


-- 
--Guido van Rossum (on iPad)
___
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] Revert #12085 fix for __del__ attribute error message

[Ethan Furman]

On 09/22/2013 08:24 PM, Nick Coghlan wrote:


On 23 Sep 2013 06:38, "Terry Reedy" mailto:tjre...@udel.edu>> wrote:


On 9/22/2013 2:41 PM, Guido van Rossum wrote:


On Sun, Sep 22, 2013 at 10:35 AM, Terry Reedy mailto:tjre...@udel.edu>
>> wrote:

On 9/21/2013 10:30 PM, Guido van Rossum wrote:

Exceptions in __del__ point to bugs (sometimes in the stdlib) that
should be fixed, period. The only reason they do not result in
exceptions that are properly bubbled up and catchable is because
__del__
is called from a DECREF macro which has no return value.


That is clear enough. What fooled me is the word 'ignored', in both
the doc and message. How about 'skipped' (for technical reasons)?


That's a good point, although I'm not sure 'skipped' is better.



Only slightly ;-). The problem with both words is that they try to say two 
things. What happened, and what Python did about it.



Maybe use a more neutral verb like 'occurred'?



"Exception occurred in ..." is even better at say what happened.

I think we should then add an explict statement as to what Python did, and hint 
at what the user should do, something like
"Although caught internally, it still indicates a problem."


Brevity is still a virtue. The relevant C API function is called 
"PyErr_WriteUnraisable", so just starting the message
as something like "Unraisable exception suppressed in..." might work.


I like that!  +1

--
~Ethan~
___
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] Enum Eccentricities

[Guido van Rossum]

On Sunday, September 22, 2013, Zero Piraeus wrote:

> I may be misunderstanding the use case given in the issue, but it seems
> to me that having to use
>
> Color.red.__class__.blue
>
> (what is being complained about in the issue), while not exactly pretty,
> makes a lot more semantic sense than
>
> Color.red.blue
>
> ... which is just bizarre.


Right.


> Enum members aren't class attributes, even if the way they're defined
> makes them look as though they are. Allowing this is just asking for
> more confusion on the part of anyone using them IMHO.
>

Depends on how you define "class sttribute".

--Guido


-- 
--Guido van Rossum (on iPad)
___
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] Revert #12085 fix for __del__ attribute error message

[Glenn Linderman]

On 9/22/2013 9:29 PM, Guido van Rossum wrote:

On Sunday, September 22, 2013, Nick Coghlan wrote:

Brevity is still a virtue. The relevant C API function is called
"PyErr_WriteUnraisable", so just starting the message as something
like "Unraisable exception suppressed in..." might work.


Somehow "unraisable" sounds too technical, and "suppressed" is hardly 
right given that it is printed...


Let's leave well enough alone.


"printable-only exception in..."
___
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

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

[Stephen J. Turnbull]

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.

Indeed.  Abstractly I agree with Steven: there are some modules such
as statistics where it would be nice for users to have long docstrings
that might even be the full source for the web docs if the module
author so prefers.

But given that Python has an existing policy of concise docstrings
(which indeed is useful when browsing code) and a separate manual, I
withdraw my support for changing practice.  (Sorry, Steven.)

___
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] Revert #12085 fix for __del__ attribute error message

[Greg Ewing]

Guido van Rossum wrote:

Somehow "unraisable" sounds too technical,


It's not even really accurate. It's been raised, it just
can't be propagated any further. But "unpropagatable
exception" would be a bit of a mouthful.

--
Greg

___
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com