FAQ
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
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 836 bytes
Desc: not available
URL: <http://mail.python.org/pipermail/doc-sig/attachments/20100413/0fa05da8/attachment.pgp>

Search Discussions

  • Bill Janssen at Apr 13, 2010 at 9:56 pm
    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Þtail&aid(95197&group_id2455&atid@5618

    Bill
  • Michael Foord at Apr 13, 2010 at 10:24 pm

    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
  • Georg Brandl at Apr 13, 2010 at 11:25 pm

    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.

    http://epydoc.sourceforge.net/epydoc.html#epydoc-fields
    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
  • Michael Foord at Apr 13, 2010 at 11:30 pm

    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 at python.org
    http://mail.python.org/mailman/listinfo/doc-sig

    --
    http://www.ironpythoninaction.com/
  • Ralf Gommers at Apr 14, 2010 at 12:26 am

    On Wed, Apr 14, 2010 at 7:30 AM, Michael Foord 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
    -------------- next part --------------
    An HTML attachment was scrubbed...
    URL: <http://mail.python.org/pipermail/doc-sig/attachments/20100414/2a7528b1/attachment-0001.html>
  • Barry Warsaw at Apr 14, 2010 at 12:40 am

    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
    -------------- next part --------------
    A non-text attachment was scrubbed...
    Name: signature.asc
    Type: application/pgp-signature
    Size: 836 bytes
    Desc: not available
    URL: <http://mail.python.org/pipermail/doc-sig/attachments/20100413/5730ac3b/attachment.pgp>
  • Nick Coghlan at Apr 14, 2010 at 1:58 pm

    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 at gmail.com | Brisbane, Australia
    ---------------------------------------------------------------
  • Barry Warsaw at Apr 14, 2010 at 2:07 pm

    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

    -------------- next part --------------
    A non-text attachment was scrubbed...
    Name: signature.asc
    Type: application/pgp-signature
    Size: 836 bytes
    Desc: not available
    URL: <http://mail.python.org/pipermail/doc-sig/attachments/20100414/6c290f00/attachment.pgp>
  • Georg Brandl at Apr 14, 2010 at 2:23 pm

    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
  • Ralf Gommers at Apr 14, 2010 at 2:48 pm

    On Wed, Apr 14, 2010 at 10:23 PM, Georg Brandl 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.

    Cheers,
    Ralf
    -------------- next part --------------
    An HTML attachment was scrubbed...
    URL: <http://mail.python.org/pipermail/doc-sig/attachments/20100414/6555ed87/attachment.html>
  • Michael Foord at Apr 14, 2010 at 2:56 pm

    On 14/04/2010 16:48, Ralf Gommers wrote:

    On Wed, Apr 14, 2010 at 10:23 PM, Georg Brandl <g.brandl at 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 at python.org
    http://mail.python.org/mailman/listinfo/doc-sig

    --
    http://www.ironpythoninaction.com/

    -------------- next part --------------
    An HTML attachment was scrubbed...
    URL: <http://mail.python.org/pipermail/doc-sig/attachments/20100414/91ccf13e/attachment-0001.html>
  • Ralf Gommers at Apr 14, 2010 at 3:13 pm

    On Wed, Apr 14, 2010 at 10:56 PM, Michael Foord 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
    -------------- next part --------------
    An HTML attachment was scrubbed...
    URL: <http://mail.python.org/pipermail/doc-sig/attachments/20100414/63ea33d3/attachment.html>
  • Michael Foord at Apr 14, 2010 at 3:22 pm

    On 14/04/2010 17:13, Ralf Gommers wrote:

    On Wed, Apr 14, 2010 at 10:56 PM, Michael Foord
    <fuzzyman at 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/

    -------------- next part --------------
    An HTML attachment was scrubbed...
    URL: <http://mail.python.org/pipermail/doc-sig/attachments/20100414/a36fccea/attachment.html>
  • Ralf Gommers at Apr 14, 2010 at 3:35 pm

    On Wed, Apr 14, 2010 at 11:22 PM, Michael Foord wrote:

    On 14/04/2010 17:13, Ralf Gommers wrote:



    On Wed, Apr 14, 2010 at 10:56 PM, Michael Foord <fuzzyman at 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
    -------------- next part --------------
    An HTML attachment was scrubbed...
    URL: <http://mail.python.org/pipermail/doc-sig/attachments/20100414/a3b5488e/attachment-0001.html>
  • Mary S. Murphy at Apr 14, 2010 at 3:46 pm
    Please get your email addresses correct. I keep getting them. Thanks.
    ----- Original Message -----
    From: Michael Foord
    To: Ralf Gommers
    Cc: doc-sig at 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 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 at python.org
    http://mail.python.org/mailman/listinfo/doc-sig
    -------------- next part --------------
    An HTML attachment was scrubbed...
    URL: <http://mail.python.org/pipermail/doc-sig/attachments/20100414/5a8a7546/attachment-0001.html>
  • A.M. Kuchling at Apr 14, 2010 at 4:00 pm

    On Wed, Apr 14, 2010 at 11:46:11AM -0400, Mary S. Murphy wrote:
    Please get your email addresses correct. I keep getting them. Thanks.
    I've removed her from the list.

    --amk
  • Fred Drake at Apr 14, 2010 at 3:24 pm

    On Wed, Apr 14, 2010 at 11:13 AM, 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.
    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
  • Michael Foord at Apr 14, 2010 at 3:25 pm

    On 14/04/2010 17:24, Fred Drake wrote:
    On Wed, Apr 14, 2010 at 11:13 AM, 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.
    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 Drake at Apr 14, 2010 at 3:29 pm

    On Wed, Apr 14, 2010 at 11:25 AM, Michael Foord 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
  • Georg Brandl at Apr 14, 2010 at 3:53 pm

    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
    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
  • Michael Foord at Apr 14, 2010 at 4:04 pm

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

    Michael
    not-name-dropping-ly y'rs,
    Georg

    _______________________________________________
    Doc-SIG maillist - Doc-SIG at python.org
    http://mail.python.org/mailman/listinfo/doc-sig

    --
    http://www.ironpythoninaction.com/
  • Fred Drake at Apr 14, 2010 at 4:36 pm

    On Wed, Apr 14, 2010 at 11:53 AM, Georg Brandl 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
  • Bill Janssen at Apr 14, 2010 at 4:59 pm

    Fred Drake wrote:
    On Wed, Apr 14, 2010 at 11:53 AM, Georg Brandl 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
  • Barry Warsaw at Apr 14, 2010 at 10:28 pm

    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
    -------------- next part --------------
    A non-text attachment was scrubbed...
    Name: signature.asc
    Type: application/pgp-signature
    Size: 836 bytes
    Desc: not available
    URL: <http://mail.python.org/pipermail/doc-sig/attachments/20100414/e81f03cf/attachment.pgp>
  • Barry Warsaw at Apr 14, 2010 at 3:43 pm

    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
    -------------- next part --------------
    A non-text attachment was scrubbed...
    Name: signature.asc
    Type: application/pgp-signature
    Size: 836 bytes
    Desc: not available
    URL: <http://mail.python.org/pipermail/doc-sig/attachments/20100414/05147703/attachment.pgp>
  • Ralf Gommers at Apr 15, 2010 at 10:39 am

    On Wed, Apr 14, 2010 at 11:43 PM, Barry Warsaw 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
    -------------- next part --------------
    An HTML attachment was scrubbed...
    URL: <http://mail.python.org/pipermail/doc-sig/attachments/20100415/2541e875/attachment.html>
  • Barry Warsaw at Apr 14, 2010 at 3:41 pm

    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
    -------------- next part --------------
    A non-text attachment was scrubbed...
    Name: signature.asc
    Type: application/pgp-signature
    Size: 836 bytes
    Desc: not available
    URL: <http://mail.python.org/pipermail/doc-sig/attachments/20100414/68641d66/attachment.pgp>
  • Michael Foord at Apr 14, 2010 at 3:59 pm

    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 at python.org
    http://mail.python.org/mailman/listinfo/doc-sig

    --
    http://www.ironpythoninaction.com/

    -------------- next part --------------
    An HTML attachment was scrubbed...
    URL: <http://mail.python.org/pipermail/doc-sig/attachments/20100414/93f1e1a7/attachment.html>
  • Michael Foord at Apr 14, 2010 at 3:37 pm

    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

    --
    http://www.ironpythoninaction.com/
  • Barry Warsaw at Apr 14, 2010 at 3:46 pm

    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
    -------------- next part --------------
    A non-text attachment was scrubbed...
    Name: signature.asc
    Type: application/pgp-signature
    Size: 836 bytes
    Desc: not available
    URL: <http://mail.python.org/pipermail/doc-sig/attachments/20100414/ac3e271c/attachment.pgp>
  • Georg Brandl at Apr 14, 2010 at 9:50 pm

    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
  • Barry Warsaw at Apr 14, 2010 at 10:27 pm

    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
    -------------- next part --------------
    A non-text attachment was scrubbed...
    Name: signature.asc
    Type: application/pgp-signature
    Size: 836 bytes
    Desc: not available
    URL: <http://mail.python.org/pipermail/doc-sig/attachments/20100414/fd5e482c/attachment.pgp>
  • Barry Warsaw at Apr 14, 2010 at 12:39 am

    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
    -------------- next part --------------
    A non-text attachment was scrubbed...
    Name: signature.asc
    Type: application/pgp-signature
    Size: 836 bytes
    Desc: not available
    URL: <http://mail.python.org/pipermail/doc-sig/attachments/20100413/7509bed6/attachment.pgp>
  • David Goodger at Apr 14, 2010 at 12:55 am

    On Tue, Apr 13, 2010 at 17:12, Barry Warsaw 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.

    http://epydoc.sourceforge.net/epydoc.html#epydoc-fields
    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>
  • Barry Warsaw at Apr 14, 2010 at 11:38 am

    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
    -------------- next part --------------
    A non-text attachment was scrubbed...
    Name: signature.asc
    Type: application/pgp-signature
    Size: 836 bytes
    Desc: not available
    URL: <http://mail.python.org/pipermail/doc-sig/attachments/20100414/dd36a4e2/attachment.pgp>
  • Michael Foord at Apr 14, 2010 at 12:44 pm

    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 at python.org
    http://mail.python.org/mailman/listinfo/doc-sig

    --
    http://www.ironpythoninaction.com/

    -------------- next part --------------
    An HTML attachment was scrubbed...
    URL: <http://mail.python.org/pipermail/doc-sig/attachments/20100414/f620501e/attachment.html>
  • Barry Warsaw at Apr 14, 2010 at 12:10 pm

    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
    -------------- next part --------------
    A non-text attachment was scrubbed...
    Name: signature.asc
    Type: application/pgp-signature
    Size: 836 bytes
    Desc: not available
    URL: <http://mail.python.org/pipermail/doc-sig/attachments/20100414/3c814481/attachment.pgp>
  • Nick Coghlan at Apr 14, 2010 at 2:27 pm

    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 at gmail.com | Brisbane, Australia
    ---------------------------------------------------------------
  • Fred Drake at Apr 14, 2010 at 2:37 pm

    On Wed, Apr 14, 2010 at 10:27 AM, Nick Coghlan 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
  • Michael Foord at Apr 14, 2010 at 2:39 pm

    On 14/04/2010 16:37, Fred Drake wrote:
    On Wed, Apr 14, 2010 at 10:27 AM, Nick Coghlanwrote:
    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 Drake at Apr 14, 2010 at 2:47 pm

    On Wed, Apr 14, 2010 at 10:39 AM, Michael Foord 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
  • Fred Drake at Apr 14, 2010 at 1:08 pm

    On Wed, Apr 14, 2010 at 8:44 AM, Michael Foord 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
  • Georg Brandl at Apr 14, 2010 at 2:26 pm

    Am 14.04.2010 13:08, schrieb Fred Drake:
    On Wed, Apr 14, 2010 at 8:44 AM, Michael Foord
    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
  • Fred Drake at Apr 14, 2010 at 2:39 pm

    On Wed, Apr 14, 2010 at 10:26 AM, Georg Brandl 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
  • Ralf Gommers at Apr 14, 2010 at 2:53 pm

    On Wed, Apr 14, 2010 at 10:39 PM, Fred Drake wrote:
    On Wed, Apr 14, 2010 at 10:26 AM, Georg Brandl 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
    -------------- next part --------------
    An HTML attachment was scrubbed...
    URL: <http://mail.python.org/pipermail/doc-sig/attachments/20100414/384c9ecb/attachment.html>

Related Discussions

Discussion Navigation
viewthread | post
Discussion Overview
groupdoc-sig @
categoriespython
postedApr 13, '10 at 9:12p
activeApr 15, '10 at 10:39a
posts46
users10
websitepython.org

People

Translate

site design / logo © 2019 Grokbase