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. Thanks in advance, -- Steve
There's not really much to do but maintain them separately. Truncate the docstrings if it makes life easier. 2013/9/21 Steven D'Aprano <steve@pearwood.info>:
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.
Thanks in advance,
-- Steve _______________________________________________ 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/benjamin%40python.org
-- Regards, Benjamin
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
On Sun, 22 Sep 2013 13:13:04 +1000 Steven D'Aprano <steve@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 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.
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 <steve@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 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
On Sun, Sep 22, 2013 at 8:53 AM, Steven D'Aprano <steve@pearwood.info>wrote:
On Sun, 22 Sep 2013 13:13:04 +1000 Steven D'Aprano <steve@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
On Sun, Sep 22, 2013 at 10:20:46AM +0200, Antoine Pitrou wrote: 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:
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.
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
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~
On Sun, Sep 22, 2013 at 8:49 AM, Barry Warsaw <barry@python.org> wrote:
On Sep 22, 2013, at 10:34 AM, Brett Cannon wrote:
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 <ref:module.py Foo.bar> # << Auto generator pastes function signature and docstring here More algorithms, more bla bla, examples. Eli
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.com@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 <steve@pearwood.info> wrote:
On Sun, 22 Sep 2013 13:13:04 +1000 Steven D'Aprano <steve@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
as "too much information" in a code review, so I'm going to assume
On Sun, Sep 22, 2013 at 10:20:46AM +0200, Antoine Pitrou wrote: that 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.
On Sun, Sep 22, 2013 at 11:02 AM, Westley Martínez <anikom15@gmail.com>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)
From: gvanrossum@gmail.com [mailto:gvanrossum@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.
On 2013-09-22, at 21:24 , Westley Martínez wrote:
From: gvanrossum@gmail.com [mailto:gvanrossum@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
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.com@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: gvanrossum@gmail.com [mailto:gvanrossum@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
On Sun, Sep 22, 2013 at 2:41 PM, Xavier Morel <python-dev@masklinn.net>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)
On Sun, 22 Sep 2013 16:19:21 -0700, Guido van Rossum <guido@python.org> wrote:
On Sun, Sep 22, 2013 at 2:41 PM, Xavier Morel <python-dev@masklinn.net>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 thing that hasn't been mentioned about docstrings vs rst docs, is that even when the text is identical, it generally isn't. By that I mean the rst docs have ReST markup, but the docstrings don't. So using autodoc doesn't just mean adding autodoc to our doc building toolchain, it *also* means adding support in pydoc for turning ReST into plain text. And that still leaves the markup in the docstring, where it will be very distracting while actually reading the source code. Which, unlike other commenters, I spend more time doing that than I do using help (and that doesn't apply to just the stdlib for me).
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.
I won't pretend that I find having to edit two places when updating fundamental documentation pleasant, but... I find that as often as not I want to word things *differently* in the docstring vs the rst docs for the same function. Sometimes the difference is subtle; most often it is an omission of detail along the lines Guido suggests. But when writing the rst version, it generally isn't that I'm simply continuing on after the first paragraph; instead, the organization of even that starting text is different, because I'm aware that the reader has a different mindset (quick help vs reference documentation) when reading the two texts.[*] As with the question of NEWS items versus checkin messages, the intended audience, or in this case the mindset of the intended audience, is *different*, and so the text should very often be different as well[**]. --David [*] I posit that this is even *more* true for those who say they only use help and only fall back to the full docs when the docstrings aren't enough. [**] I also wonder if long function docstrings have a negative impact on usability in IDEs that pop up windows with docstring information in them.
On 09/23/2013 04:43 PM, R. David Murray wrote:
On Sun, 22 Sep 2013 16:19:21 -0700, Guido van Rossum <guido@python.org> wrote:
On Sun, Sep 22, 2013 at 2:41 PM, Xavier Morel <python-dev@masklinn.net>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 thing that hasn't been mentioned about docstrings vs rst docs, is that even when the text is identical, it generally isn't. By that I mean the rst docs have ReST markup, but the docstrings don't. So using
FYI, the scientific Python community have their own standard (the NumPy docstring standard), with light RST markup in docstrings: https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt It's a fairly popular standard in the scientific sub-culture. I think there's something about scientific codes which tips the scales away from Guido's position of short docstrings being better; when working with computation, you pretty much need the documentation, formulas, references to paper it is based on and so on in order to read and understand the code in the first place, so interspersing makes more sense than it may in the stdlib. Seeing code with references "x", "alpha", "beta", "gamma" without their definition is pretty useless :-) Dag Sverre
On 22.09.13 16:34, Brett Cannon wrote:
The rule of thumb I go by is the docstring should be enough to answer the question "what args does this thing take and what does it do in general to know it's the function I want and another one in the same module?" quickly and succinctly; i.e. just enough so that help() reminds you about details for a module you are already familiar with that might come up while at the interpreter prompt. Everything else -- in-depth discussion of the algorithms, extra examples, why you want to use this function, etc. -- all go in the .rst docs.
It would be great if the docstring contained a link to the online documentation. Servus, Walter
On Mon, Sep 23, 2013 at 7:27 AM, Walter Dörwald <walter@livinglogic.de> wrote:
It would be great if the docstring contained a link to the online documentation.
The docstring itself, or the presentation generated by help() ? -Fred -- Fred L. Drake, Jr. <fred at fdrake.net> "A storm broke loose in my mind." --Albert Einstein
On 23.09.13 15:38, Fred Drake wrote:
On Mon, Sep 23, 2013 at 7:27 AM, Walter Dörwald <walter@livinglogic.de> wrote:
It would be great if the docstring contained a link to the online documentation.
The docstring itself, or the presentation generated by help() ?
The presentation generated by help(), or the output of IPython's foo? or foo?? syntax. Servus, Walter
Le Mon, 23 Sep 2013 15:51:27 +0200, Walter Dörwald <walter@livinglogic.de> a écrit :
On 23.09.13 15:38, Fred Drake wrote:
On Mon, Sep 23, 2013 at 7:27 AM, Walter Dörwald <walter@livinglogic.de> wrote:
It would be great if the docstring contained a link to the online documentation.
The docstring itself, or the presentation generated by help() ?
The presentation generated by help(), or the output of IPython's foo? or foo?? syntax.
Perhaps objects could gain some kind of optional __docurl__ attribute, to avoid cluttering __doc__ with external links. Not sure how that could be auto-generated, though (we certainly don't want to maintain doc links manually). Regards Antoine.
It would be great if the docstring contained a link to the online documentation.
That would have to be a feature of help(), not hardcoded in each docstring.
That *is* a feature of the help function: Help on built-in module sys:
help(sys) NAME sys
FILE (built-in) MODULE DOCS http://docs.python.org/library/sys ... (pydoc too, though I'm 99.9% sure they use the same underlying facility Ping originally implemented.) Skip
On 9/23/2013 11:18 AM, Skip Montanaro wrote:
It would be great if the docstring contained a link to the online documentation.
That would have to be a feature of help(), not hardcoded in each docstring.
That *is* a feature of the help function:
Help on built-in module sys:
help(sys) NAME sys
FILE (built-in)
MODULE DOCS http://docs.python.org/library/sys
On 3.3.2 and 3.4.0: Help on built-in module sys: NAME sys MODULE REFERENCE http://docs.python.org/3.3/library/sys ... FILE (built-in) On Windows, one will not see the top of the help(sys) output unless one either uses Idle or increases the number of lines in the console window from 300. -- Terry Jan Reedy
On 23.09.13 17:18, Skip Montanaro wrote:
It would be great if the docstring contained a link to the online documentation.
That would have to be a feature of help(), not hardcoded in each docstring.
That *is* a feature of the help function:
Help on built-in module sys:
help(sys) NAME sys
FILE (built-in)
MODULE DOCS http://docs.python.org/library/sys ...
(pydoc too, though I'm 99.9% sure they use the same underlying facility Ping originally implemented.)
Hmm, but it doesn't work for functions:
import sys help(sys.settracee)
Help on built-in function settrace in module sys: settrace(...) settrace(function) Set the global debug tracing function. It will be called on each function call. See the debugger chapter in the library manual. Servus, Walter
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
On 22 September 2013 18:54, Georg Brandl <g.brandl@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 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 | ncoghlan@gmail.com | Brisbane, Australia
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.
On 09/22/2013 12:16 PM, Nick Coghlan wrote:
On 22 September 2013 18:54, Georg Brandl <g.brandl@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 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 <docstring would go here in the output> 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
On Sat, Sep 21, 2013 at 8:13 PM, Steven D'Aprano <steve@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 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
On 09/22/2013 02:54 PM, Eli Bendersky wrote:
On Sat, Sep 21, 2013 at 8:13 PM, Steven D'Aprano <steve@pearwood.info <mailto:steve@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 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
On Sun, Sep 22, 2013 at 6:06 AM, Georg Brandl <g.brandl@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 <steve@pearwood.info <mailto:steve@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
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
important documentation. Sometimes we forget that most Python
the more 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
On 23 September 2013 00:16, Eli Bendersky <eliben@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 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 | ncoghlan@gmail.com | Brisbane, Australia
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
On 22 September 2013 13:54, Eli Bendersky <eliben@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 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
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.
On Sun, Sep 22, 2013 at 9:53 AM, Stephen J. Turnbull <stephen@xemacs.org>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)
On Sun, Sep 22, 2013 at 10:07 AM, Guido van Rossum <guido@python.org> wrote:
On Sun, Sep 22, 2013 at 9:53 AM, Stephen J. Turnbull <stephen@xemacs.org>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
On Sun, Sep 22, 2013 at 10:25 AM, Eli Bendersky <eliben@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 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)
On Sun, Sep 22, 2013 at 11:40 AM, Guido van Rossum <guido@python.org> wrote:
On Sun, Sep 22, 2013 at 10:25 AM, Eli Bendersky <eliben@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 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
On Sun, Sep 22, 2013 at 11:44 AM, Eli Bendersky <eliben@gmail.com> wrote:
On Sun, Sep 22, 2013 at 11:40 AM, Guido van Rossum <guido@python.org>wrote:
On Sun, Sep 22, 2013 at 10:25 AM, Eli Bendersky <eliben@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 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 <a href="(what goes here?)">foobar</a>. :-)
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)
Am 23.09.2013 00:03, schrieb Guido van Rossum:
AFAIU, the proposal is to embed parts of the concise docstring into the more verbose .rst documentation.
I still think that's a bad idea. Someone editing the docstring may introduce a terminology change or some other style/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).
Yes, this style is better suited for smaller documentations where there isn't that much more info in the .rst than in the docstring -- the .rst giving maybe an introduction and then just a logical order in which docstrings are pulled. Since we have the policy (now reconfirmed) of small docstrings and more verbose prose on docs.python.org, this would not be feasible there.
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 agree that is another good point. And should the "suggest a change on docs.python.org" feature ever be shipped, it will be much harder, if not impossible, to generate a patch and let developers submit it automatically.
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 <a href="(what goes here?)">foobar</a>. :-)
PSA: I can only recommend to everyone not to take up Guido's dare... (and I'm not terribly proud of that). cheers, Georg
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
On Sun, Sep 22, 2013 at 5:31 PM, Steven D'Aprano <steve@pearwood.info>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)
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
On Sun, Sep 22, 2013 at 7:25 PM, Terry Reedy <tjreedy@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, 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)
On 09/23/2013 03:44 AM, Guido van Rossum wrote:
On Sun, Sep 22, 2013 at 7:25 PM, Terry Reedy <tjreedy@udel.edu <mailto:tjreedy@udel.edu>> wrote:
I am gradually changing Idle docstrings, though only Idle developers will ever see them. Writing a 60 char summary forces a clear understanding of the function.
Glad you like it. I still do, too, but I've given up hope to convince all core developers to stick to this style. :-(
... Argument Clinic to the rescue? Since the last time this subject came up, Clinic has started enforcing a summary line in docstrings. I didn't realize it had to be 60 columns though, should I add that? Is the entire docstring supposed to be 60 columns max? p.s. status update: AC is done enough to be worth considering checking in. Now I have to finish the PEP and write the documentation. //arry/
On Mon, Sep 23, 2013 at 12:57 AM, Larry Hastings <larry@hastings.org> wrote:
On 09/23/2013 03:44 AM, Guido van Rossum wrote:
On Sun, Sep 22, 2013 at 7:25 PM, Terry Reedy <tjreedy@udel.edu> wrote:
I am gradually changing Idle docstrings, though only Idle developers will ever see them. Writing a 60 char summary forces a clear understanding of the function.
Glad you like it. I still do, too, but I've given up hope to convince all core developers to stick to this style. :-(
... Argument Clinic to the rescue? Since the last time this subject came up, Clinic has started enforcing a summary line in docstrings. I didn't realize it had to be 60 columns though, should I add that? Is the entire docstring supposed to be 60 columns max?
I think 60 is just a guideline. In stdlib .py source code I want it not to extend beyond the 79th column (see recent PEP 8 argument). For a typical class, where the docstring is indented 4 spaces, that leaves 72 characters for the summary line (including a final period!). For a method it's 68 due to the extra indent. FWIW I also prefer having the summary line on the same line as the opening """: def foo(): """This is the summary. This is the rest. """
p.s. status update: AC is done enough to be worth considering checking in. Now I have to finish the PEP and write the documentation.
-- --Guido van Rossum (python.org/~guido)
On 9/23/2013 10:56 AM, Guido van Rossum wrote:
I think 60 is just a guideline. In stdlib .py source code I want it not to extend beyond the 79th column (see recent PEP 8 argument). For a
PEP 8 says "Limit all lines to a maximum of 79 characters. For flowing long blocks of text with fewer structural restrictions (docstrings or comments), the line length should be limited to 72 characters." I do not understand 72 instead of 79, but to me, that means 72 chars total, including indents, triple quote and period, which means the cursor not past 73. If that is not what you mean, please clarify.
typical class, where the docstring is indented 4 spaces, that leaves 72 characters for the summary line (including a final period!). For a method it's 68 due to the extra indent.
72 - 2 indents - """ - . = 60, which is a bit skimpy ;-). Why not the full 79 at least? -- Terry Jan Reedy
On Mon, Sep 23, 2013 at 10:52 AM, Terry Reedy <tjreedy@udel.edu> wrote:
On 9/23/2013 10:56 AM, Guido van Rossum wrote:
I think 60 is just a guideline. In stdlib .py source code I want it not
to extend beyond the 79th column (see recent PEP 8 argument). For a
PEP 8 says "Limit all lines to a maximum of 79 characters.
For flowing long blocks of text with fewer structural restrictions (docstrings or comments), the line length should be limited to 72 characters."
I do not understand 72 instead of 79, but to me, that means 72 chars total, including indents, triple quote and period, which means the cursor not past 73. If that is not what you mean, please clarify.
This is partly based on Emacs defaults (when I hit ESC-q, it reflows a paragraph using the 72 char limit), partly on old punched card conventions (columns 73-80 were reserved for sequence numbers), partly just to limit the line length to of *columns* of text to something a bit narrower than the full line width (i.e. 80 chars) to improve readability. But the PEP specifically qualifies this with "for flowing long blocks of text" which is meant to apply only to blocks of reflowable text that don't fit on a line. If it fits on a line, you can go to 79.
typical class, where the docstring is indented 4 spaces, that leaves 72 characters for the summary line (including a final period!). For a method it's 68 due to the extra indent.
72 - 2 indents - """ - . = 60, which is a bit skimpy ;-). Why not the full
79 at least?
For the summary line, that's fine (and actually how I interpret the PEP). -- --Guido van Rossum (python.org/~guido)
On Mon, 23 Sep 2013 08:57:01 +0100 Larry Hastings <larry@hastings.org> wrote:
On 09/23/2013 03:44 AM, Guido van Rossum wrote:
On Sun, Sep 22, 2013 at 7:25 PM, Terry Reedy <tjreedy@udel.edu <mailto:tjreedy@udel.edu>> wrote:
I am gradually changing Idle docstrings, though only Idle developers will ever see them. Writing a 60 char summary forces a clear understanding of the function.
Glad you like it. I still do, too, but I've given up hope to convince all core developers to stick to this style. :-(
... Argument Clinic to the rescue? Since the last time this subject came up, Clinic has started enforcing a summary line in docstrings. I didn't realize it had to be 60 columns though, should I add that? Is the entire docstring supposed to be 60 columns max?
p.s. status update: AC is done enough to be worth considering checking in. Now I have to finish the PEP and write the documentation.
I hope it can make it in for 3.4 :) cheers Antoine.
On 9/22/2013 10:44 PM, Guido van Rossum wrote:
Glad you like it. I still do, too, but I've given up hope to convince all core developers to stick to this style. :-(
[me] ('Return' rather than 'Returns' is the current convention.)
That's actually a religious argument which in the stdlib takes no strict position -- a quick grep shows that both are used, although 'Return' is more frequent by a 5-to-1 margin.
In the .rst docs, 'Return' versus 'Returns', exact uppercase word match, is a little over 3 to 1. I am sure I have seen 'Return' and similiar directive forms ('Print', 'Store', 'Compare', etc) recommended as current doc style, as prefered by the current doc crew.
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.)
My take is that 'Returns' describes to the programmer what the function (interpreter) does, while 'Return' says what the programmer says to the interpreter when using the function. I strongly prefer the directive form. Why? For one thing, *because* it is different from normal descriptive text, such as the first sentence of this paragraph. For another, the descriptive form seems addressed to me as code reader while the directive form seems addressed to me as code writer. For me, the latter seems more energizing. -- Terry Jan Reedy
On 23/09/2013 20:01, Terry Reedy wrote:
On 9/22/2013 10:44 PM, Guido van Rossum wrote:
Glad you like it. I still do, too, but I've given up hope to convince all core developers to stick to this style. :-(
[me] ('Return' rather than 'Returns' is the current convention.)
That's actually a 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.
In the .rst docs, 'Return' versus 'Returns', exact uppercase word match, is a little over 3 to 1. I am sure I have seen 'Return' and similiar directive forms ('Print', 'Store', 'Compare', etc) recommended as current doc style, as prefered by the current doc crew.
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.)
My take is that 'Returns' describes to the programmer what the function (interpreter) does, while 'Return' says what the programmer says to the interpreter when using the function. I strongly prefer the directive form. Why? For one thing, *because* it is different from normal descriptive text, such as the first sentence of this paragraph. For another, the descriptive form seems addressed to me as code reader while the directive form seems addressed to me as code writer. For me, the latter seems more energizing.
<pedantic>I think you mean "imperative" vs "indicative".</pedantic>
On Mon, Sep 23, 2013 at 3:01 PM, Terry Reedy <tjreedy@udel.edu> wrote:
IIRC in the Java world you *have* to
use 'Returns', but I don't buy the argument from nit-picky grammarians that leads to this rule. (It's something about the documentation not being a command. But English is more flexible than that.)
My take is that 'Returns' describes to the programmer what the function (interpreter) does, while 'Return' says what the programmer says to the interpreter when using the function. I strongly prefer the directive form.
+1 I don't think "Returns bar." is a valid English sentence because it lacks subject. I would not mind def foo(): """returns bar""" which I would read as "Function foo() returns bar," but in this case "returns" should be in lower case.
This is getting off-topic, if you're not interested in English grammar you should stop reading. On Mon, Sep 23, 2013 at 03:18:01PM -0400, Alexander Belopolsky wrote:
I don't think "Returns bar." is a valid English sentence because it lacks subject.
Subjectless sentences are unusual in English, but you do see them. Sentences consisting of only an interjection are subjectless: "Ouch!" "Hear hear!" "Rubbish!" "Oh dear!" Imperative sentences often have no explicit subject: "Close the door." "Put that light out!" "Follow me." Conversational English (especially spoken English) often displays the phenomenon called "Conversational Deletion", where the beginning of sentences are eroded away, dropping (e.g.) possessives, articles, and subject nouns. "Hope this helps." "See you next week." "No need to get upset!" In the example given, "Returns bar", I would identify this as an example of conversational deletion. The full sentence would be "This function returns bar". Personally, I don't mind such a conversational style, although many people consider it too informal for written English, even docstrings :-)
I would not mind
def foo(): """returns bar"""
which I would read as "Function foo() returns bar," but in this case "returns" should be in lower case.
I certainly don't like that. Sentences, even eroded sentences, start with capital letters in English. Unless you are the poet e.e. cummings, capital letters are non-negotiable. -- Steven
Given near-consensus on the "Return ..." form, the following discussion is of academic interest only. On Mon, Sep 23, 2013 at 9:31 PM, Steven D'Aprano <steve@pearwood.info>wrote:
I would not mind
def foo(): """returns bar"""
which I would read as "Function foo() returns bar," but in this case "returns" should be in lower case.
I certainly don't like that. Sentences, even eroded sentences, start with capital letters in English. Unless you are the poet e.e. cummings, capital letters are non-negotiable.
I still believe "Returns bar." is a non-sentence even if "Return bar!" is. While absence of subject noun in itself may not be an issue, but combined with a singular third-person verb form, it makes "Returns bar." grammatically incorrect.
On Mon, Sep 23, 2013 at 3:01 PM, Terry Reedy <tjreedy@udel.edu> wrote:
'Return' versus 'Returns', exact uppercase word match, is a little over 3 to 1. I am sure I have seen 'Return' and similiar directive forms ('Print', 'Store', 'Compare', etc) recommended as current doc style, as prefered by the current doc crew.
I don't know about the current crew, but this dates way back to Guido's initial LaTeX documentation, and Guido's strong preference on this. -Fred -- Fred L. Drake, Jr. <fred at fdrake.net> "A storm broke loose in my mind." --Albert Einstein
On 9/22/2013 10:44 PM, Guido van Rossum wrote:
On Sun, Sep 22, 2013 at 7:25 PM, Terry Reedy <tjreedy@udel.edu
('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.
I wrote 'current convention' not just as a statistical statement, but as a prescription I had read, even though I did not remember just where. PEP8 says "PEP 257 describes good docstring conventions." I followed that clue found the statement I had read. PEP 257 says ''' It [the one line docstring] prescribes the function or method's effect as a command ("Do this", "Return that"), not as a description; e.g. don't write "Returns the pathname ...". ''' Whether the reference in PEP 8 makes it a PEP 8 rule? or a 'strict stdlib position'? http://bugs.python.org/issue19067 proposes to change rangeobject docstrings. Is that OK or should the issue be rejected and closed? -- Terry Jan Reedy
Guido van Rossum writes:
On Sun, Sep 22, 2013 at 5:31 PM, Steven D'Aprano <steve@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 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.)
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
On Sun, Sep 22, 2013 at 5:07 PM, Steven D'Aprano <steve@pearwood.info>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)
participants (26)
-
Alexander Belopolsky -
Antoine Pitrou -
Barry Warsaw -
Benjamin Peterson -
Brett Cannon -
Dag Sverre Seljebotn -
Eli Bendersky -
Ethan Furman -
Fred Drake -
Georg Brandl -
Guido van Rossum -
Larry Hastings -
MRAB -
Nick Coghlan -
Paul Moore -
R. David Murray -
Skip Montanaro -
Stephen J. Turnbull -
Stephen J. Turnbull -
Steven D'Aprano -
Terry Reedy -
Victor Stinner -
Walter Dörwald -
Westley Martínez -
Xavier Morel -
Xavier Morel