epydoc reST markup for stdlib docstrings
Hello Doc-Siggers, During some recent work on the PEP 3147, I had a need to add some documentation (docstrings) to some new functions. To document the function arguments I added epydoc reST style markup: def ensure_bytecode_path(bytecode_path): """Ensure that the __pycache__ directory for PEP 3147 pyc file exists. :param bytecode_path: File system path to PEP 3147 pyc file. """ Now, I didn't even think twice about this because several of the larger Python projects I work on have already adopted epydoc reST markup for API. During his review, Antoine disapproved of this, pointing to PEPs 257 and 287. My reading of these PEPs however, certainly doesn't prohibit the use of epydoc reST markup. Georg and I pointed to the lack of a clear, consistent convention in the Python stdlib. I would like to propose that epydoc reST markup be made that convention. http://epydoc.sourceforge.net/epydoc.html#epydoc-fields PEP 257 does include an example for keyword arguments, but not much more is said about them. epydoc reST markup is compliant with PEP 287 IMO, by adopting reST syntax. I think Sphinx does a pretty good job of handling such API markup too. A PEP might be necessary to make this a firm decision. What do you think about adopting epydoc reST markup for documenting the stdlib API? -Barry
Good with me, but... Is epydoc still being maintained? The last release was over two years ago, and the current release (3.0) doesn't work with the current docutils (0.6). https://sourceforge.net/tracker/?func=detail&aid=2895197&group_id=32455&atid=405618 Bill
On 13/04/2010 23:56, Bill Janssen wrote:
Good with me, but...
Is epydoc still being maintained? The last release was over two years ago, and the current release (3.0) doesn't work with the current docutils (0.6).
I don't think that is particularly relevant to the proposal. The proposal is that we adopt a standard, once we have done that other tools can be built that use it. Epydoc maybe essentially dead but it doesn't affect the quality (or otherwise) of the docstring standard. Michael
https://sourceforge.net/tracker/?func=detail&aid=2895197&group_id=32455&atid=405618
Bill _______________________________________________ Doc-SIG maillist - Doc-SIG@python.org http://mail.python.org/mailman/listinfo/doc-sig
Am 13.04.2010 21:12, schrieb Barry Warsaw:
Hello Doc-Siggers,
During some recent work on the PEP 3147, I had a need to add some documentation (docstrings) to some new functions. To document the function arguments I added epydoc reST style markup:
def ensure_bytecode_path(bytecode_path): """Ensure that the __pycache__ directory for PEP 3147 pyc file exists.
:param bytecode_path: File system path to PEP 3147 pyc file. """
Now, I didn't even think twice about this because several of the larger Python projects I work on have already adopted epydoc reST markup for API. During his review, Antoine disapproved of this, pointing to PEPs 257 and 287. My reading of these PEPs however, certainly doesn't prohibit the use of epydoc reST markup. Georg and I pointed to the lack of a clear, consistent convention in the Python stdlib. I would like to propose that epydoc reST markup be made that convention.
So far, so good, but I would *not* want to make a ":param foo:" section a recommendation or even mandatory. (IMO it's too verbose, parameters can be explained in the text just fine.) Valid reST is a first goal, and it should be achievable to slowly convert docstrings to that.
PEP 257 does include an example for keyword arguments, but not much more is said about them. epydoc reST markup is compliant with PEP 287 IMO, by adopting reST syntax. I think Sphinx does a pretty good job of handling such API markup too.
Yes, I've tried to be compatible to what Epydoc supports.
A PEP might be necessary to make this a firm decision. What do you think about adopting epydoc reST markup for documenting the stdlib API?
From me, +1.
(Also for this reason: Many projects pull docstrings into their Sphinx docs via autodoc these days, and some also document inherited APIs. When these inherited APIs come from the stdlib, the markup is often confusing or not even valid reST.) Georg
On 14/04/2010 01:25, Georg Brandl wrote:
[snip...]
A PEP might be necessary to make this a firm decision. What do you think about adopting epydoc reST markup for documenting the stdlib API?
From me, +1.
(Also for this reason: Many projects pull docstrings into their Sphinx docs via autodoc these days, and some also document inherited APIs. When these inherited APIs come from the stdlib, the markup is often confusing or not even valid reST.)
Definite +1 from me on adopting reST in docstrings as a standard. I haven't looked at the Epydoc convention for parameters (etc) well enough to have an opinion on that. Michael Foord
Georg
_______________________________________________ Doc-SIG maillist - Doc-SIG@python.org http://mail.python.org/mailman/listinfo/doc-sig
On Wed, Apr 14, 2010 at 7:30 AM, Michael Foord <fuzzyman@voidspace.org.uk>wrote:
On 14/04/2010 01:25, Georg Brandl wrote:
[snip...]
A PEP might be necessary to make this a firm decision. What do you think
about adopting epydoc reST markup for documenting the stdlib API?
From me, +1.
(Also for this reason: Many projects pull docstrings into their Sphinx docs via autodoc these days, and some also document inherited APIs. When these inherited APIs come from the stdlib, the markup is often confusing or not even valid reST.)
Definite +1 from me on adopting reST in docstrings as a standard. I haven't looked at the Epydoc convention for parameters (etc) well enough to have an opinion on that.
Agreed that a reST based standard would be very useful.
One point that is important to me (and many scientific users) is how the docstring looks in a terminal. Numpy has been developing a standard for docstrings and writing docs that both looks good in plain text and in docs rendered with Sphinx. http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines This is quickly becoming a standard for scientific projects (numpy, scipy, matplotlib, ipython etc). For an example see http://docs.scipy.org/numpy/docs/numpy.core.multiarray.arange/, click "source" for plain text version. Basic format is: """Summary line. Parameters ------------ param1 : int Description of param1. Can be multi-line. param2: array Description of param2. Returns ------- val1 : float Example ------- <examples in doctest format> """ There is also a very nice wiki doc editor with svn merging support (into the wiki automatic, patch generation for import into svn) here: http://docs.scipy.org/numpy/docs/. As far as I can tell the epydoc standard is not nearly as readable as the numpy standard in plain text, so please consider the latter or something similar for adoption. Best regards, Ralf
On Apr 14, 2010, at 01:30 AM, Michael Foord wrote:
Definite +1 from me on adopting reST in docstrings as a standard. I haven't looked at the Epydoc convention for parameters (etc) well enough to have an opinion on that.
The thing I like about them is that the rules are very simple, and once learned are easy to remember. -Barry
Barry Warsaw wrote:
On Apr 14, 2010, at 01:30 AM, Michael Foord wrote:
Definite +1 from me on adopting reST in docstrings as a standard. I haven't looked at the Epydoc convention for parameters (etc) well enough to have an opinion on that.
The thing I like about them is that the rules are very simple, and once learned are easy to remember.
Did you look at the NumPy guidelines Ralf posted?: http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines Those look very clean to me, and fairly similar to what we already do in the ReST docs. Because epydoc works with tags rather than sections, it looks a lot "noisier" to me when reading the plain text version. Cheers, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia ---------------------------------------------------------------
On Apr 14, 2010, at 11:58 PM, Nick Coghlan wrote:
Barry Warsaw wrote:
On Apr 14, 2010, at 01:30 AM, Michael Foord wrote:
Definite +1 from me on adopting reST in docstrings as a standard. I haven't looked at the Epydoc convention for parameters (etc) well enough to have an opinion on that.
The thing I like about them is that the rules are very simple, and once learned are easy to remember.
Did you look at the NumPy guidelines Ralf posted?: http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines
Those look very clean to me, and fairly similar to what we already do in the ReST docs.
Because epydoc works with tags rather than sections, it looks a lot "noisier" to me when reading the plain text version.
And I'm not keen on the sections since I think they consume too much vertical whitespace. And I like the tags of epydoc format on the left side for their regularity. Everyone's got a different opinion, and the only one that matters is the BDFL's. :) OTOH, the specifics don't matter as much as just picking one for the stdlib. -Barry
Am 14.04.2010 14:07, schrieb Barry Warsaw:
On Apr 14, 2010, at 11:58 PM, Nick Coghlan wrote:
Barry Warsaw wrote:
On Apr 14, 2010, at 01:30 AM, Michael Foord wrote:
Definite +1 from me on adopting reST in docstrings as a standard. I haven't looked at the Epydoc convention for parameters (etc) well enough to have an opinion on that.
The thing I like about them is that the rules are very simple, and once learned are easy to remember.
Did you look at the NumPy guidelines Ralf posted?: http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines
Those look very clean to me, and fairly similar to what we already do in the ReST docs.
Because epydoc works with tags rather than sections, it looks a lot "noisier" to me when reading the plain text version.
And I'm not keen on the sections since I think they consume too much vertical whitespace. And I like the tags of epydoc format on the left side for their regularity.
Also, the numpy docstring conventions also aren't valid reST and therefore need preprocessing. (Making them reST isn't hard but requires even more vertical space.) Georg
On Apr 14, 2010, at 11:58 PM, Nick Coghlan wrote:
Barry Warsaw wrote:
On Apr 14, 2010, at 01:30 AM, Michael Foord wrote:
Definite +1 from me on adopting reST in docstrings as a standard. I haven't looked at the Epydoc convention for parameters (etc) well enough to have an opinion on that.
The thing I like about them is that the rules are very simple, and once learned are easy to remember.
Did you look at the NumPy guidelines Ralf posted?: http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines
Those look very clean to me, and fairly similar to what we already do in the ReST docs.
Because epydoc works with tags rather than sections, it looks a lot "noisier" to me when reading the plain text version.
And I'm not keen on the sections since I think they consume too much vertical whitespace. And I like the tags of epydoc format on the left side for
Am 14.04.2010 14:07, schrieb Barry Warsaw: their
regularity.
Also, the numpy docstring conventions also aren't valid reST and therefore need preprocessing. (Making them reST isn't hard but requires even more vertical space.)
The preprocessing should not be an issue, especially since the code for
On Wed, Apr 14, 2010 at 10:23 PM, Georg Brandl <g.brandl@gmx.net> wrote: that already exists and is heavily used. The vertical whitespace vs tags is a taste issue, I agree, from a developer perspective. From a user perspective however, the numpy standard is clearly more readable in a terminal. That's why it looks the way it does. And reading docstrings in a terminal is not a fringe use case by the way. Cheers, Ralf
On 14/04/2010 16:48, Ralf Gommers wrote:
On Wed, Apr 14, 2010 at 10:23 PM, Georg Brandl <g.brandl@gmx.net <mailto:g.brandl@gmx.net>> wrote:
Am 14.04.2010 14:07, schrieb Barry Warsaw: > On Apr 14, 2010, at 11:58 PM, Nick Coghlan wrote: > >>Barry Warsaw wrote: >>> On Apr 14, 2010, at 01:30 AM, Michael Foord wrote: >>> >>>> Definite +1 from me on adopting reST in docstrings as a standard. I >>>> haven't looked at the Epydoc convention for parameters (etc) well enough >>>> to have an opinion on that. >>> >>> The thing I like about them is that the rules are very simple, and once >>> learned are easy to remember. >> >>Did you look at the NumPy guidelines Ralf posted?: >>http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines >> >>Those look very clean to me, and fairly similar to what we already do in >>the ReST docs. >> >>Because epydoc works with tags rather than sections, it looks a lot >>"noisier" to me when reading the plain text version. > > And I'm not keen on the sections since I think they consume too much vertical > whitespace. And I like the tags of epydoc format on the left side for their > regularity.
Also, the numpy docstring conventions also aren't valid reST and therefore need preprocessing. (Making them reST isn't hard but requires even more vertical space.)
The preprocessing should not be an issue, especially since the code for that already exists and is heavily used.
The vertical whitespace vs tags is a taste issue, I agree, from a developer perspective. From a user perspective however, the numpy standard is clearly more readable in a terminal. That's why it looks the way it does. And reading docstrings in a terminal is not a fringe use case by the way.
I would say that reading docstrings in a terminal is the *main* use case - but that is why I tend to value the vertical space highly and personally prefer the less verbose way. Michael
Cheers, Ralf
_______________________________________________ Doc-SIG maillist - Doc-SIG@python.org http://mail.python.org/mailman/listinfo/doc-sig
On Wed, Apr 14, 2010 at 10:56 PM, Michael Foord <fuzzyman@voidspace.org.uk>wrote:
On 14/04/2010 16:48, Ralf Gommers wrote:
The vertical whitespace vs tags is a taste issue, I agree, from a developer perspective. From a user perspective however, the numpy standard is clearly more readable in a terminal. That's why it looks the way it does. And reading docstrings in a terminal is not a fringe use case by the way.
I would say that reading docstrings in a terminal is the *main* use case - but that is why I tend to value the vertical space highly and personally prefer the less verbose way.
You're a core developer (I think). But for the *average* user, do you really think tags are fine? Earlier in this thread there was a mention of people that love to read XML. I'm exaggerating a bit of course, but this is similar. Whitespace beats tags for readability. Ralf
On 14/04/2010 17:13, Ralf Gommers wrote:
On Wed, Apr 14, 2010 at 10:56 PM, Michael Foord <fuzzyman@voidspace.org.uk <mailto:fuzzyman@voidspace.org.uk>> wrote:
On 14/04/2010 16:48, Ralf Gommers wrote:
The vertical whitespace vs tags is a taste issue, I agree, from a developer perspective. From a user perspective however, the numpy standard is clearly more readable in a terminal. That's why it looks the way it does. And reading docstrings in a terminal is not a fringe use case by the way.
I would say that reading docstrings in a terminal is the *main* use case - but that is why I tend to value the vertical space highly and personally prefer the less verbose way.
You're a core developer (I think). But for the *average* user, do you really think tags are fine? Earlier in this thread there was a mention of people that love to read XML. I'm exaggerating a bit of course, but this is similar. Whitespace beats tags for readability.
Well, docstrings that take up several screens worth of console and scroll out of view like merry abandon are horrible. We should do real usability testing (with 'real' users) if we really want an answer. Michael
Ralf
On Wed, Apr 14, 2010 at 11:22 PM, Michael Foord <fuzzyman@voidspace.org.uk>wrote:
On 14/04/2010 17:13, Ralf Gommers wrote:
On Wed, Apr 14, 2010 at 10:56 PM, Michael Foord <fuzzyman@voidspace.org.uk
wrote:
On 14/04/2010 16:48, Ralf Gommers wrote:
The vertical whitespace vs tags is a taste issue, I agree, from a developer perspective. From a user perspective however, the numpy standard is clearly more readable in a terminal. That's why it looks the way it does. And reading docstrings in a terminal is not a fringe use case by the way.
I would say that reading docstrings in a terminal is the *main* use case - but that is why I tend to value the vertical space highly and personally prefer the less verbose way.
You're a core developer (I think). But for the *average* user, do you really think tags are fine? Earlier in this thread there was a mention of people that love to read XML. I'm exaggerating a bit of course, but this is similar. Whitespace beats tags for readability.
Well, docstrings that take up several screens worth of console and scroll out of view like merry abandon are horrible.
In many cases yes, but that is a totally different issue. The example Nick posted was 17 lines for numpy standard vs 15 lines for epydoc standard.
We should do real usability testing (with 'real' users) if we really want an answer.
That sounds like a good idea.
Cheers, Ralf
Please get your email addresses correct. I keep getting them. Thanks. ----- Original Message ----- From: Michael Foord To: Ralf Gommers Cc: doc-sig@python.org Sent: Wednesday, April 14, 2010 11:22 AM Subject: Re: [Doc-SIG] epydoc reST markup for stdlib docstrings On 14/04/2010 17:13, Ralf Gommers wrote: On Wed, Apr 14, 2010 at 10:56 PM, Michael Foord <fuzzyman@voidspace.org.uk> wrote: On 14/04/2010 16:48, Ralf Gommers wrote: The vertical whitespace vs tags is a taste issue, I agree, from a developer perspective. From a user perspective however, the numpy standard is clearly more readable in a terminal. That's why it looks the way it does. And reading docstrings in a terminal is not a fringe use case by the way. I would say that reading docstrings in a terminal is the *main* use case - but that is why I tend to value the vertical space highly and personally prefer the less verbose way. You're a core developer (I think). But for the *average* user, do you really think tags are fine? Earlier in this thread there was a mention of people that love to read XML. I'm exaggerating a bit of course, but this is similar. Whitespace beats tags for readability. Well, docstrings that take up several screens worth of console and scroll out of view like merry abandon are horrible. We should do real usability testing (with 'real' users) if we really want an answer. Michael Ralf -- http://www.ironpythoninaction.com/ ------------------------------------------------------------------------------ _______________________________________________ Doc-SIG maillist - Doc-SIG@python.org http://mail.python.org/mailman/listinfo/doc-sig
On Wed, Apr 14, 2010 at 11:13 AM, Ralf Gommers <ralf.gommers@googlemail.com> wrote:
You're a core developer (I think). But for the *average* user, do you really think tags are fine? Earlier in this thread there was a mention of people that love to read XML. I'm exaggerating a bit of course, but this is similar. Whitespace beats tags for readability.
All consumers of docstrings are programmers. Maybe only by necessity, but they are. Frankly, terminals and any other window just can't handle all that much text on the typical horizontal monitor, placing a premium on vertical whitespace. Widescreen is good for movies, but sucks for general-purpose computer monitors. -Fred -- Fred L. Drake, Jr. <fdrake at gmail.com> "Chaos is the score upon which reality is written." --Henry Miller
On 14/04/2010 17:24, Fred Drake wrote:
On Wed, Apr 14, 2010 at 11:13 AM, Ralf Gommers <ralf.gommers@googlemail.com> wrote:
You're a core developer (I think). But for the *average* user, do you really think tags are fine? Earlier in this thread there was a mention of people that love to read XML. I'm exaggerating a bit of course, but this is similar. Whitespace beats tags for readability.
All consumers of docstrings are programmers. Maybe only by necessity, but they are.
Frankly, terminals and any other window just can't handle all that much text on the typical horizontal monitor, placing a premium on vertical whitespace.
Widescreen is good for movies, but sucks for general-purpose computer monitors.
They're great if you turn them sideways though... Michael
-Fred
On Wed, Apr 14, 2010 at 11:25 AM, Michael Foord <fuzzyman@voidspace.org.uk> wrote:
They're great if you turn them sideways though...
Indeed they are! All monitors are improved in that arrangement. -Fred -- Fred L. Drake, Jr. <fdrake at gmail.com> "Chaos is the score upon which reality is written." --Henry Miller
Am 14.04.2010 15:25, schrieb Michael Foord:
On 14/04/2010 17:24, Fred Drake wrote:
On Wed, Apr 14, 2010 at 11:13 AM, Ralf Gommers <ralf.gommers@googlemail.com> wrote:
You're a core developer (I think). But for the *average* user, do you really think tags are fine? Earlier in this thread there was a mention of people that love to read XML. I'm exaggerating a bit of course, but this is similar. Whitespace beats tags for readability.
All consumers of docstrings are programmers. Maybe only by necessity, but they are.
Frankly, terminals and any other window just can't handle all that much text on the typical horizontal monitor, placing a premium on vertical whitespace.
Widescreen is good for movies, but sucks for general-purpose computer monitors.
They're great if you turn them sideways though...
Uh, or just use an editor that can usefully display three files side-by-side. not-name-dropping-ly y'rs, Georg
On 14/04/2010 17:53, Georg Brandl wrote:
Am 14.04.2010 15:25, schrieb Michael Foord:
On 14/04/2010 17:24, Fred Drake wrote:
On Wed, Apr 14, 2010 at 11:13 AM, Ralf Gommers <ralf.gommers@googlemail.com> wrote:
You're a core developer (I think). But for the *average* user, do you really think tags are fine? Earlier in this thread there was a mention of people that love to read XML. I'm exaggerating a bit of course, but this is similar. Whitespace beats tags for readability.
All consumers of docstrings are programmers. Maybe only by necessity, but they are.
Frankly, terminals and any other window just can't handle all that much text on the typical horizontal monitor, placing a premium on vertical whitespace.
Widescreen is good for movies, but sucks for general-purpose computer monitors.
They're great if you turn them sideways though...
Uh, or just use an editor that can usefully display three files side-by-side.
Like Wing? http://skitch.com/fuzzyman/n6581/wing-ide-vera-backend.wpr-views.py-vera-mai... Michael
not-name-dropping-ly y'rs, Georg
_______________________________________________ Doc-SIG maillist - Doc-SIG@python.org http://mail.python.org/mailman/listinfo/doc-sig
On Wed, Apr 14, 2010 at 11:53 AM, Georg Brandl <g.brandl@gmx.net> wrote:
Uh, or just use an editor that can usefully display three files side-by-side.
Hmmm... Three monitors, each with three files side by side, oriented vertically. More monitors for email and browsers, of course. Sounds like an ideal coding platform to me! -Fred -- Fred L. Drake, Jr. <fdrake at gmail.com> "Chaos is the score upon which reality is written." --Henry Miller
Fred Drake <fdrake@acm.org> wrote:
On Wed, Apr 14, 2010 at 11:53 AM, Georg Brandl <g.brandl@gmx.net> wrote:
Uh, or just use an editor that can usefully display three files side-by-side.
Hmmm... Three monitors, each with three files side by side, oriented vertically. More monitors for email and browsers, of course. Sounds like an ideal coding platform to me!
I've been using this for a bit -- three 1200x1600 monitors in portrait mode driven by a Mac Pro. Not bad, but at my boss's urging I've recently replaced two of them with an Apple 30" Cinema display. Bit more resolution, 2560x1600, but I find the absence of the gap is a good thing. Bill
On Apr 14, 2010, at 09:59 AM, Bill Janssen wrote:
I've been using this for a bit -- three 1200x1600 monitors in portrait mode driven by a Mac Pro. Not bad, but at my boss's urging I've recently replaced two of them with an Apple 30" Cinema display. Bit more resolution, 2560x1600, but I find the absence of the gap is a good thing.
I'm pretty sure I hate you now. :) -Barry
On Apr 14, 2010, at 11:13 PM, Ralf Gommers wrote:
You're a core developer (I think). But for the *average* user, do you really think tags are fine? Earlier in this thread there was a mention of people that love to read XML. I'm exaggerating a bit of course, but this is similar. Whitespace beats tags for readability.
Well, I would think that help output, whether in a terminal or online would use the raw text to do a nicer job of formatting. It's source code readability that concerns me. -Barry
On Wed, Apr 14, 2010 at 11:43 PM, Barry Warsaw <barry@python.org> wrote:
On Apr 14, 2010, at 11:13 PM, Ralf Gommers wrote:
You're a core developer (I think). But for the *average* user, do you really think tags are fine? Earlier in this thread there was a mention of people that love to read XML. I'm exaggerating a bit of course, but this is similar. Whitespace beats tags for readability.
Well, I would think that help output, whether in a terminal or online would use the raw text to do a nicer job of formatting.
If it looks good in help() (and ipython) then I have no problem with it. You would have to preprocess each docstring each time it's viewed though, instead of only when generating html docs. But if it's robust, then sure, it's a non-issue. Cheers, Ralf
On Apr 14, 2010, at 04:56 PM, Michael Foord wrote:
I would say that reading docstrings in a terminal is the *main* use case - but that is why I tend to value the vertical space highly and personally prefer the less verbose way.
I agree about the vertical whitespace when reading in the terminal. You also want compact output for online docs too though. I'm tempted to say that whatever Georg implements in Sphinx is good enough for me. :) -Barry
On 14/04/2010 17:41, Barry Warsaw wrote:
On Apr 14, 2010, at 04:56 PM, Michael Foord wrote:
I would say that reading docstrings in a terminal is the *main* use case - but that is why I tend to value the vertical space highly and personally prefer the less verbose way.
I agree about the vertical whitespace when reading in the terminal. You also want compact output for online docs too though.
I'm tempted to say that whatever Georg implements in Sphinx is good enough for me. :)
I completely agree that Georg is the man to take this forward and complete the task... :-) Michael
-Barry
_______________________________________________ Doc-SIG maillist - Doc-SIG@python.org http://mail.python.org/mailman/listinfo/doc-sig
On 14/04/2010 16:07, Barry Warsaw wrote:
On Apr 14, 2010, at 11:58 PM, Nick Coghlan wrote:
Barry Warsaw wrote:
On Apr 14, 2010, at 01:30 AM, Michael Foord wrote:
Definite +1 from me on adopting reST in docstrings as a standard. I haven't looked at the Epydoc convention for parameters (etc) well enough to have an opinion on that.
The thing I like about them is that the rules are very simple, and once learned are easy to remember.
Did you look at the NumPy guidelines Ralf posted?: http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines
Those look very clean to me, and fairly similar to what we already do in the ReST docs.
Because epydoc works with tags rather than sections, it looks a lot "noisier" to me when reading the plain text version.
And I'm not keen on the sections since I think they consume too much vertical whitespace. And I like the tags of epydoc format on the left side for their regularity. Everyone's got a different opinion, and the only one that matters is the BDFL's. :)
Well, perhaps move this discussion to python-dev with the intent of creating a PEP and asking for BDFL pronouncement? The two contenders seem to be numpy format and epydoc format. We seem to have a consensus that adopting a standard for the standard library is a good idea. Once we have settled on a basic format we can thrash out all the specifics in the PEP. All the best, Michael
OTOH, the specifics don't matter as much as just picking one for the stdlib.
-Barry
On Apr 14, 2010, at 05:37 PM, Michael Foord wrote:
Well, perhaps move this discussion to python-dev with the intent of creating a PEP and asking for BDFL pronouncement? The two contenders seem to be numpy format and epydoc format. We seem to have a consensus that adopting a standard for the standard library is a good idea.
Once we have settled on a basic format we can thrash out all the specifics in the PEP.
I agree. Right now I've got enough big PEPs on my plate that I'm not willing to take on another one right now. Maybe I've sufficiently tempted/goaded/guilted/excited someone else to though. ;) -Barry
Am 14.04.2010 17:46, schrieb Barry Warsaw:
On Apr 14, 2010, at 05:37 PM, Michael Foord wrote:
Well, perhaps move this discussion to python-dev with the intent of creating a PEP and asking for BDFL pronouncement? The two contenders seem to be numpy format and epydoc format. We seem to have a consensus that adopting a standard for the standard library is a good idea.
Once we have settled on a basic format we can thrash out all the specifics in the PEP.
I agree. Right now I've got enough big PEPs on my plate that I'm not willing to take on another one right now. Maybe I've sufficiently tempted/goaded/guilted/excited someone else to though. ;)
Yes, I'll write that PEP. Don't expect it too soon though. cheers, Georg
On Apr 14, 2010, at 11:50 PM, Georg Brandl wrote:
Am 14.04.2010 17:46, schrieb Barry Warsaw:
I agree. Right now I've got enough big PEPs on my plate that I'm not willing to take on another one right now. Maybe I've sufficiently tempted/goaded/guilted/excited someone else to though. ;)
Yes, I'll write that PEP. Don't expect it too soon though.
My evil plan worked! :) Thanks Georg. -Barry
On Apr 13, 2010, at 11:25 PM, Georg Brandl wrote:
So far, so good, but I would *not* want to make a ":param foo:" section a recommendation or even mandatory. (IMO it's too verbose, parameters can be explained in the text just fine.) Valid reST is a first goal, and it should be achievable to slowly convert docstrings to that.
I actually find prose descriptions of parameters and return values much harder to read. YMMV of course. We can definitely agree on valid reST being the top priority, as PEP 287 states. Even this of course is not mandatory (yet). I think it is useful to be more prescriptive, such that if folks want to markup their parameters in other than prose, epydoc reST style is the officially preferred format to use. That way, we can begin to standardize the stdlib, and build and extend tools that read that format.
PEP 257 does include an example for keyword arguments, but not much more is said about them. epydoc reST markup is compliant with PEP 287 IMO, by adopting reST syntax. I think Sphinx does a pretty good job of handling such API markup too.
Yes, I've tried to be compatible to what Epydoc supports.
Excellent.
A PEP might be necessary to make this a firm decision. What do you think about adopting epydoc reST markup for documenting the stdlib API?
From me, +1.
(Also for this reason: Many projects pull docstrings into their Sphinx docs via autodoc these days, and some also document inherited APIs. When these inherited APIs come from the stdlib, the markup is often confusing or not even valid reST.)
Yep. I'd love to see guidelines and stronger recommendations that people can follow so that over time, we fix this. Thanks, -Barry
On Tue, Apr 13, 2010 at 17:12, Barry Warsaw <barry@python.org> wrote:
During some recent work on the PEP 3147, I had a need to add some documentation (docstrings) to some new functions. To document the function arguments I added epydoc reST style markup:
def ensure_bytecode_path(bytecode_path): """Ensure that the __pycache__ directory for PEP 3147 pyc file exists.
:param bytecode_path: File system path to PEP 3147 pyc file. """
Now, I didn't even think twice about this because several of the larger Python projects I work on have already adopted epydoc reST markup for API. During his review, Antoine disapproved of this, pointing to PEPs 257 and 287. My reading of these PEPs however, certainly doesn't prohibit the use of epydoc reST markup.
PEP 257 doesn't address docstring syntax at all, just conventions. PEP 287 addresses "only the low-level syntax of docstrings". IOW, these PEPs don't apply to Antoine's concern. High-level semantics simply aren't addressed by them. (As the author or co-author, I should know :-) I once wrote up some notes about docstring semantics: http://docutils.sourceforge.net/docs/dev/semantics.html
Georg and I pointed to the lack of a clear, consistent convention in the Python stdlib. I would like to propose that epydoc reST markup be made that convention.
I'm not a fan of epydoc's conventions (too much like JavaDoc, too verbose, too strict). On the other hand, "now is better than never" -- working code and rough consensus rule. I wouldn't object to making the epydoc field conventions *a* standard convention, allowing for others. Just as choice of markup is very much a matter of personal preference (some people *love* dealing with XML directly), choice of API documentation semantics is also a personal preference thing. We would be wise to allow for choice. -- David Goodger <http://python.net/~goodger>
On Apr 13, 2010, at 08:55 PM, David Goodger wrote:
I'm not a fan of epydoc's conventions (too much like JavaDoc, too verbose, too strict). On the other hand, "now is better than never" -- working code and rough consensus rule. I wouldn't object to making the epydoc field conventions *a* standard convention, allowing for others.
Just as choice of markup is very much a matter of personal preference (some people *love* dealing with XML directly), choice of API documentation semantics is also a personal preference thing. We would be wise to allow for choice.
Perhaps it would be useful to survey some popular and/or large Python code bases to see what is currently being used? That would be a good start to try to figure out what the stdlib should recommend. I do think that we should make strong recommendations for the standard library, so that we have consistency and good online documentation. I personally like epydoc reST format (not JavaDoc) but I'm sure there are other decent formats. -Barry
On 14/04/2010 13:38, Barry Warsaw wrote:
On Apr 13, 2010, at 08:55 PM, David Goodger wrote:
I'm not a fan of epydoc's conventions (too much like JavaDoc, too verbose, too strict). On the other hand, "now is better than never" -- working code and rough consensus rule. I wouldn't object to making the epydoc field conventions *a* standard convention, allowing for others.
Just as choice of markup is very much a matter of personal preference (some people *love* dealing with XML directly), choice of API documentation semantics is also a personal preference thing. We would be wise to allow for choice.
Perhaps it would be useful to survey some popular and/or large Python code bases to see what is currently being used? That would be a good start to try to figure out what the stdlib should recommend.
I do think that we should make strong recommendations for the standard library, so that we have consistency and good online documentation. I personally like epydoc reST format (not JavaDoc) but I'm sure there are other decent formats.
I'm not aware of other formats beyond epydoc and javadoc (I agree with your opinion on javadoc) - oh and the .NET xml format which I strongly recommend we steer clear of. Do you have any references? I don't recall *ever* seeing a consistent pattern for specifying parameters and return values in Python docstrings. I too would prefer a consistent pattern be adopted for the Python standard library. Good luck finding someone to go and change all the docstrings in the standard library to use it... Michael
-Barry
_______________________________________________ Doc-SIG maillist - Doc-SIG@python.org http://mail.python.org/mailman/listinfo/doc-sig
On Apr 14, 2010, at 02:44 PM, Michael Foord wrote:
I'm not aware of other formats beyond epydoc and javadoc (I agree with your opinion on javadoc) - oh and the .NET xml format which I strongly recommend we steer clear of. Do you have any references?
XML is not human readable or writable (IMNSHO :). As far as epydoc, this is probably the only page you care about: http://epydoc.sourceforge.net/manual-fields.html It describes the fields that are used to describe parameters, return types, and exceptions. Note that while the body of that page uses "Epytext" format, the table near the top of the page shows the three alternative syntaxes. Of those of course I recommend reST (the middle column). You have to mentally translate the syntax in the body of the page to reST though. Keep in mind too that it's not always necessary to include *every* field in a function's docstring. Obviously, include only what is useful to the consumer of the function's documentation. For example, when it's completely obvious, or when I actually don't know (e.g. because the method proxies some other method 3 levels deep), I might not include the :type: field. I also won't include obvious, common exceptions. I do think *that* can be left to the author's taste. Here's an example: def inject_message(mlist, msg, recips=None, switchboard=None, **kws): """Inject a message into a queue. :param mlist: The mailing list this message is destined for. :type mlist: `IMailingList` :param msg: The message object to inject. :type msg: `email.message.Message` or derived :param recips: Optional set of recipients to put into the message's metadata. :type recips: sequence of strings :param switchboard: Optional name of switchboard to inject this message into. If not given, the 'in' switchboard is used. :type switchboard: string :param kws: Additional values for the message metadata. :type kws: dictionary """ Note that :param: values are complete sentences, while :type: values are informative types, not necessarily explicit types (e.g. an interface for mlist and 'string' instead of 'str' or 'unicode' for switchboard). This function doesn't return anything and doesn't explicitly raise any exceptions. The implicit KeyErrors that could be raised are not described.
I don't recall *ever* seeing a consistent pattern for specifying parameters and return values in Python docstrings.
Exactly. :)
I too would prefer a consistent pattern be adopted for the Python standard library. Good luck finding someone to go and change all the docstrings in the standard library to use it...
Like all other coding standards we have for the stdlib, the migration can happen opportunistically over time. But folks need a target or nothing will ever happen. -Barry
Barry Warsaw wrote:
Here's an example:
def inject_message(mlist, msg, recips=None, switchboard=None, **kws): """Inject a message into a queue.
:param mlist: The mailing list this message is destined for. :type mlist: `IMailingList` :param msg: The message object to inject. :type msg: `email.message.Message` or derived :param recips: Optional set of recipients to put into the message's metadata. :type recips: sequence of strings :param switchboard: Optional name of switchboard to inject this message into. If not given, the 'in' switchboard is used. :type switchboard: string :param kws: Additional values for the message metadata. :type kws: dictionary """
Since the NumPy conventions seem to be the only real alternative proposed so far, here's what the above would look like (according to my ever so comprehensive 5 minute skim of those guidelines, anyway...) def inject_message(mlist, msg, recips=None, switchboard=None, **kws): """Inject a message into a queue. Parameters ---------- mlist : IMailingList The mailing list this message is destined for. msg : email.message.Message (or derived) The message object to inject. recips : sequence of strings, optional Optional set of recipients to put into the message's metadata. switchboard : string, optional Optional name of switchboard to inject this message into. If not given, the 'in' switchboard is used. kws : dictionary, optional Additional values for the message metadata. """ Basically, the numpy format trades a couple of lines of whitespace for the section header to get rid of the tag noise in the individual parameter descriptions. The ", optional" parts seem rather redundant (since they are implied by the function signature itself), but the guidelines say to include them, so I included them. It seems to me that the exceptional keyword arguments are those which are required, not those which are optional. Cheers, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia ---------------------------------------------------------------
On Wed, Apr 14, 2010 at 10:27 AM, Nick Coghlan <ncoghlan@gmail.com> wrote:
The ", optional" parts seem rather redundant (since they are implied by the function signature itself), but the guidelines say to include them, so I included them. It seems to me that the exceptional keyword arguments are those which are required, not those which are optional.
This has always been a source of tension in documenting Python: a certain amount of information is available in the signature, but the signature of the implementation function isn't always the same as the signature of the contract. Documentation needs the later. Interfaces help, if you use them (ABCs kinda, if you follow that school of thought). Unfortunately, there's not really a way currently to tell the difference between "default implementation" and "contract" in ABCs, which is all stock Python provides. -Fred -- Fred L. Drake, Jr. <fdrake at gmail.com> "Chaos is the score upon which reality is written." --Henry Mille
On 14/04/2010 16:37, Fred Drake wrote:
On Wed, Apr 14, 2010 at 10:27 AM, Nick Coghlan<ncoghlan@gmail.com> wrote:
The ", optional" parts seem rather redundant (since they are implied by the function signature itself), but the guidelines say to include them, so I included them. It seems to me that the exceptional keyword arguments are those which are required, not those which are optional.
This has always been a source of tension in documenting Python: a certain amount of information is available in the signature, but the signature of the implementation function isn't always the same as the signature of the contract. Documentation needs the later.
Interfaces help, if you use them (ABCs kinda, if you follow that school of thought). Unfortunately, there's not really a way currently to tell the difference between "default implementation" and "contract" in ABCs, which is all stock Python provides.
Right - and included in the contract can be details like what exceptions an API raises. We don't necessarily need a standard to specify that (?) but it is the sort of information that ought to be in docstrings where relevant. Michael
-Fred
On Wed, Apr 14, 2010 at 10:39 AM, Michael Foord <fuzzyman@voidspace.org.uk> wrote:
Right - and included in the contract can be details like what exceptions an API raises. We don't necessarily need a standard to specify that (?) but it is the sort of information that ought to be in docstrings where relevant.
Yep. I was really just wanting to emphasize that extracting information from the signature is likely to be wrong. Unless there's a way to say explicitly that it's right. (Which would require a known interpretation, which isn't really as easy as it sounds.) -Fred -- Fred L. Drake, Jr. <fdrake at gmail.com> "Chaos is the score upon which reality is written." --Henry Miller
On Wed, Apr 14, 2010 at 8:44 AM, Michael Foord <fuzzyman@voidspace.org.uk> wrote:
I too would prefer a consistent pattern be adopted for the Python standard library. Good luck finding someone to go and change all the docstrings in the standard library to use it...
We found someone interested in converting the LaTeX to ReST, didn't we? :-) If we can come up with a good recommendation, it'll take hold fairly thoroughly. Not quickly at first, but once there's value (tools) to be had it'll happen. The value for the standard library is that the documentation maintenance can be moved closer to the code, and is less likely to get out of sync. -Fred -- Fred L. Drake, Jr. <fdrake at gmail.com> "Chaos is the score upon which reality is written." --Henry Miller
Am 14.04.2010 13:08, schrieb Fred Drake:
On Wed, Apr 14, 2010 at 8:44 AM, Michael Foord <fuzzyman@voidspace.org.uk> wrote:
I too would prefer a consistent pattern be adopted for the Python standard library. Good luck finding someone to go and change all the docstrings in the standard library to use it...
We found someone interested in converting the LaTeX to ReST, didn't we? :-)
That was a more interesting task :) However, I'm not opposed to doing stupid, repetitive things every now and then, and I hope I can find a few others to share the task.
If we can come up with a good recommendation, it'll take hold fairly thoroughly. Not quickly at first, but once there's value (tools) to be had it'll happen.
The value for the standard library is that the documentation maintenance can be moved closer to the code, and is less likely to get out of sync.
Exactly. Georg
On Wed, Apr 14, 2010 at 10:26 AM, Georg Brandl <g.brandl@gmx.net> wrote:
That was a more interesting task :) However, I'm not opposed to doing stupid, repetitive things every now and then, and I hope I can find a few others to share the task.
Agreed the task was more interesting. Also, I wasn't suggesting that we should sucker you into another such task, but just noting that someone's likely to find the outcome sufficiently valuable. And yes, multiple hands would be better. -Fred -- Fred L. Drake, Jr. <fdrake at gmail.com> "Chaos is the score upon which reality is written." --Henry Miller
On Wed, Apr 14, 2010 at 10:39 PM, Fred Drake <fdrake@acm.org> wrote:
On Wed, Apr 14, 2010 at 10:26 AM, Georg Brandl <g.brandl@gmx.net> wrote:
That was a more interesting task :) However, I'm not opposed to doing stupid, repetitive things every now and then, and I hope I can find a few others to share the task.
Agreed the task was more interesting.
Also, I wasn't suggesting that we should sucker you into another such task, but just noting that someone's likely to find the outcome sufficiently valuable. And yes, multiple hands would be better.
Pydocweb (http://code.google.com/p/pydocweb/) is very good for this. It's an svn-aware wiki docstring editor. For numpy/scipy about 100 people are registered, most of whom have contributed, from a few bug fixes to thousands of words.
A python committer would only need to review changes and apply patches. It's a great way to get contributions from new people. Cheers, Ralf
participants (10)
-
A.M. Kuchling -
Barry Warsaw -
Bill Janssen -
David Goodger -
Fred Drake -
Georg Brandl -
Mary S. Murphy -
Michael Foord -
Nick Coghlan -
Ralf Gommers