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
On Sat, 21 Sep 2013 19:55:05 -0400
Terry Reedy tjre...@udel.edu 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,
On Sun, 22 Sep 2013 13:13:04 +1000
Steven D'Aprano st...@pearwood.info 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
On 09/22/2013 10:19 AM, Antoine Pitrou wrote:
On Sat, 21 Sep 2013 19:55:05 -0400
Terry Reedy tjre...@udel.edu 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),
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
On Sun, 22 Sep 2013 10:48:33 +0200
Georg Brandl g.bra...@gmx.net wrote:
On 09/22/2013 10:19 AM, Antoine Pitrou wrote:
On Sat, 21 Sep 2013 19:55:05 -0400
Terry Reedy tjre...@udel.edu wrote:
In the general case it represents a bug in
the code that should be fixed. Most such errors
On 22 September 2013 18:54, Georg Brandl g.bra...@gmx.net 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
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
On 09/22/2013 12:16 PM, Nick Coghlan wrote:
On 22 September 2013 18:54, Georg Brandl g.bra...@gmx.net 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
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 st...@pearwood.info 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
On Sat, Sep 21, 2013 at 8:13 PM, Steven D'Aprano st...@pearwood.infowrote:
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
On 09/22/2013 02:54 PM, Eli Bendersky wrote:
On Sat, Sep 21, 2013 at 8:13 PM, Steven D'Aprano st...@pearwood.info
mailto:st...@pearwood.info wrote:
Hi all,
I have a question about how I should manage documentation for the
statistics module for Python 3.4. At the moment,
On 22 September 2013 13:54, Eli Bendersky eli...@gmail.com 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
On Sun, Sep 22, 2013 at 6:06 AM, Georg Brandl g.bra...@gmx.net wrote:
On 09/22/2013 02:54 PM, Eli Bendersky wrote:
On Sat, Sep 21, 2013 at 8:13 PM, Steven D'Aprano st...@pearwood.info
mailto:st...@pearwood.info wrote:
Hi all,
I have a question about how I should manage
On 23 September 2013 00:16, Eli Bendersky eli...@gmail.com 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
On Sun, Sep 22, 2013 at 8:53 AM, Steven D'Aprano st...@pearwood.infowrote:
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 st...@pearwood.info wrote:
Hi all,
I have a question about how I should manage documentation
On 22 Sep 2013, at 05:25, Benjamin Peterson benja...@python.org 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.
___
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
On Sun, Sep 22, 2013 at 8:49 AM, Barry Warsaw ba...@python.org 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
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*
On Sun, Sep 22, 2013 at 9:53 AM, Stephen J. Turnbull step...@xemacs.orgwrote:
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
On Sun, Sep 22, 2013 at 10:07 AM, Guido van Rossum gu...@python.org wrote:
On Sun, Sep 22, 2013 at 9:53 AM, Stephen J. Turnbull
step...@xemacs.orgwrote:
Eli Bendersky writes:
IMHO the right way to think about it is that the .rst files are by
far the more important documentation.
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
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
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
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:
On Sun, Sep 22, 2013 at 11:02 AM, Westley Martínez aniko...@gmail.comwrote:
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
On Sun, Sep 22, 2013 at 10:25 AM, Eli Bendersky eli...@gmail.com 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
On Sun, Sep 22, 2013 at 10:35 AM, Terry Reedy 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
On Sun, Sep 22, 2013 at 11:40 AM, Guido van Rossum gu...@python.org wrote:
On Sun, Sep 22, 2013 at 10:25 AM, Eli Bendersky eli...@gmail.com 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.
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
On 9/22/2013 2:41 PM, Guido van Rossum wrote:
On Sun, Sep 22, 2013 at 10:35 AM, Terry Reedy tjre...@udel.edu
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,
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
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
On Sun, Sep 22, 2013 at 11:44 AM, Eli Bendersky eli...@gmail.com wrote:
On Sun, Sep 22, 2013 at 11:40 AM, Guido van Rossum gu...@python.orgwrote:
On Sun, Sep 22, 2013 at 10:25 AM, Eli Bendersky eli...@gmail.com wrote:
I think there's a general agreement in this thread that we don't intend
On Sun, Sep 22, 2013 at 2:41 PM, Xavier Morel python-...@masklinn.netwrote:
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
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
On Sun, Sep 22, 2013 at 5:07 PM, Steven D'Aprano st...@pearwood.infowrote:
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
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
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
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
On Sun, Sep 22, 2013 at 5:31 PM, Steven D'Aprano st...@pearwood.infowrote:
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
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
On Sun, Sep 22, 2013 at 4:52 PM, Ethan Furman et...@stoneleaf.us wrote:
http://bugs.python.org/**issue19011 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
On Sun, Sep 22, 2013 at 7:25 PM, Terry Reedy tjre...@udel.edu 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,
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
___
On 23 Sep 2013 06:38, Terry Reedy 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 tjre...@udel.edu
mailto:tjre...@udel.edu wrote:
On 9/21/2013 10:30 PM, Guido van Rossum wrote:
Exceptions in __del__ point to
:
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
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
On 09/22/2013 08:24 PM, Nick Coghlan wrote:
On 23 Sep 2013 06:38, Terry Reedy tjre...@udel.edu
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 tjre...@udel.edu
mailto:tjre...@udel.edu
mailto:tjre...@udel.edu
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
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.
Guido van Rossum writes:
On Sun, Sep 22, 2013 at 5:31 PM, Steven D'Aprano st...@pearwood.info 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
53 matches
Mail list logo
