Mailman 3 June 2009 - SciPy-Dev

Summer Marathon: targeting a category per week
by David Goldsmith June 25, 2009

June 25, 2009

Hi, folks! So, one of the ideas that came out of last week's Skypecon for increasing participation in the Marathon is to pick a category each week to target for "completion" (meaning Marathon goal met = getting every function to at least the "needs first review" stage) by the following week's Skypecon. No one nominated any categories last week, but I'm not giving up that easily ;-). I hereby call for suggestions for a target category for this week (i.e., to be completed by next Wed. July 1) but if I don't receive any by tomorrow morning my time (UTC-7), I'll just choose. :-) Thanks! DG

1 0

Final reminder: Numpy Doc Summer Marathon Skypecon tomorrow
by David Goldsmith June 24, 2009

June 24, 2009

i.e., Wednesday, June 24th, 19:00 UTC. Please get me your Skype ID prior to that if you want to participate. Thanks! DG

1 0

Re: [SciPy-dev] Doc-ing classes and data attributes
by David Goldsmith June 23, 2009

June 23, 2009

--- On Sat, 6/20/09, Ralf Gommers <ralf.gommers(a)googlemail.com> wrote: > On Sat, Jun 20, 2009 at 8:41 PM, > David Goldsmith <d_l_goldsmith(a)yahoo.com> > wrote: > > Thanks, Pierre, this is helpful, but the given example > doesn't have any of the _other_ sections Functions have, > though the docstring standard says "all but Returns are > relevant," so I'm left wondering where to insert > the "new" sections relative to the > "old." (I know that not _all_ Function sections > will always be relevant for _all_ classes, but I assume at > least some of them will be relevant for some classes, but > your example doesn't clarify where to put them.) But, > FWIW, thanks. > > Look at ndarray for an example: http://docs.scipy.org/numpy/docs/numpy.ndarray/#numpy-ndarray > > Documenting the class indeed means its __init__ > function as far as Parameters, See Also, Examples, etc. This > is what has been done so far for all classes I've looked > at. > > The Methods and Attributes sections show up automatically, > and contain all public methods/attributes, so don't > worry about putting a list of those in. Those > methods/attributes do have their own docstrings. If I may have edit privileges at http://projects.scipy.org/numpy/wiki/ I can add these clarifications there myself; otherwise, I'll file a ticket at pydocweb. DG > Cheers, > > Ralf > > > > > DG > > > > --- On Sat, 6/20/09, Pierre GM <pgmdevlist(a)gmail.com> > wrote: > > > > > From: Pierre GM <pgmdevlist(a)gmail.com> > > > Subject: Re: [SciPy-dev] Doc-ing > classes and data attributes > > > To: "SciPy Developers List" <scipy-dev(a)scipy.org> > > > Date: Saturday, June 20, 2009, 5:06 PM > > > > > > On Jun 20, 2009, at 7:23 PM, David Goldsmith wrote: > > > > > > > > > > > Ok, a couple follow-up questions: where > precisely > > > should > > > > documentation of __init__, and the Attributes > and > > > Methods sections > > > > (when needed) go? In other words, > > > docstringstandard says, "Use the > > > > same sections as outlined [for Functions]," > but as > > > Functions don't > > > > have __init__, Attributes, or Methods, it is > unclear > > > where in the > > > > "above" template these new items should > go. > > > > > > My 2c: > > > > > > * I don't document __init__, but I put a > 'Parameters' > > > section in the > > > docstring of the class that describes all the input > > > parameters of > > > __init__ > > > * Methods could be described in the docstring of the > class, > > > under a > > > 'Methods' entry, but it might be more > appropriate to > > > document them > > > outside the class. > > > * Same thing for Attributes: you could have a small > list in > > > the > > > docstring, but as soon as you start documenting an > > > attribute in > > > detail, you'd better have a separate section. > > > > > > Check http://pytseries.sourceforge.net/core.timeseries.html > > > for an > > > example of application. > > > > > > > > > _______________________________________________ > > > Scipy-dev mailing list > > > Scipy-dev(a)scipy.org > > > http://mail.scipy.org/mailman/listinfo/scipy-dev > > > > > > > > > > > _______________________________________________ > > Scipy-dev mailing list > > Scipy-dev(a)scipy.org > > http://mail.scipy.org/mailman/listinfo/scipy-dev > > > > > -----Inline Attachment Follows----- > > _______________________________________________ > Scipy-dev mailing list > Scipy-dev(a)scipy.org > http://mail.scipy.org/mailman/listinfo/scipy-dev >

7 22

Minutes from last week's Marathon Skypecon and Reminder for next one
by David Goldsmith June 22, 2009

June 22, 2009

Hi, folks! This week's Numpy Doc Summer Marathon Skypecon will be Wednesday, June 24, 19:00 UTC (15:00 EDT, for example). And below are Minutes of the last week's. Bye, DG Numpy Doc Summer '09 Marathon June 18, 2009 Skypecon Minutes Start: 12:30 UTC End: 13:15 UTC Present: David Goldsmith, Secretary Joe Harrington Stefan van der Walt Discussions: Low recruitment Stefan suggested putting out very specific, small goals as less intimidating Joe suggested a weekly goal, e.g., a particular category each week to try to finish off Joe suggested appealing to prominent individuals in target constituencies, asking them to appeal to their constituencies for volunteers Joe also noted that low production so far can be interpreted by the volunteer pool as low general interest, i.e., show some production and we may see greater recruitment Low Skypecon participation discussed time zone differences and tried to come up w/ a time that might be more universally "user-friendly"; arrived at Wednesday's, 19:00 UTC decided to check this time w/ VIP's Review procedure Discussed dividing the review requirement into two separate reviews, a technical review and a presentation review, both of which need to pass before the item can be passed on to the proof stage Decided that this should be vetted by the scipy-dev community before making implementation of it an "issue" on pydocweb Wiki features Discussed addition of a "click on a name, get a list of that person's work" feature to the Wiki; subsequently added as an issue on pydocweb Discussed auto-updating and caching the Milestones page periodically to reduce load times; subsequently added as an issue on pydocweb Relationship between the docstrings, the reference rst files, and the Wiki This discussion became rather fragmented - uncertain if any real "center" coalesced Notes: Had technical difficulties, primarily w/ DG being dropped, ultimately had to resort to group text messaging, which was awkward

1 0

Re: [SciPy-dev] Doc-ing classes and data attributes
by David Goldsmith June 22, 2009

June 22, 2009

Boy, did I open a can of worms! :-( DG --- On Mon, 6/22/09, Robert Kern <robert.kern(a)gmail.com> wrote: > From: Robert Kern <robert.kern(a)gmail.com> > Subject: Re: [SciPy-dev] Doc-ing classes and data attributes > To: "SciPy Developers List" <scipy-dev(a)scipy.org> > Date: Monday, June 22, 2009, 9:19 AM > 2009/6/22 Stéfan van der Walt <stefan(a)sun.ac.za> > > > > 2009/6/22 Pauli Virtanen <pav(a)iki.fi>: > > >> We have to decide: is it OK to document the > class constructor in > > >> __init__? We used to put this in the class > docstring itself so that > > >> "help" and IPython's "?" would find it, but I > don't think this is longer > > >> necessary. On the other hand, it makes > sense: you call "x = MyClass()" > > >> to construct, not "x = MyClass.__init__()". > Comments welcome. > > > > > > IMHO, it would be clearer if the __init__ method > was documented > > > separately. It can be included on the same page > in the Sphinx output as > > > the class quite easily. This would allow separate > referring to the class > > > constructor via eg. :ref:`ndarray > <ndarray.__init__>` which might result > > > to cleaner documentation. > > > > I wouldn't mind changing this part of the standard. > Robert, I > > remember you had a preference last time, do you want > to comment? > > I have always preferred documenting the __init__'s > Parameters in the > class docstring because one calls the class object itself. > > -- > Robert Kern > > "I have come to believe that the whole world is an enigma, > a harmless > enigma that is made terrible by our own mad attempt to > interpret it as > though it had an underlying truth." > -- Umberto Eco > _______________________________________________ > Scipy-dev mailing list > Scipy-dev(a)scipy.org > http://mail.scipy.org/mailman/listinfo/scipy-dev >

3 2

Re: [SciPy-dev] Doc-ing classes and data attributes
by d_l_goldsmith＠yahoo.com June 21, 2009

June 21, 2009

OK, ticket (#1146) filed. DG --- On Sun, 6/21/09, Stéfan van der Walt <stefan(a)sun.ac.za> wrote: > From: Stéfan van der Walt <stefan(a)sun.ac.za> > Subject: Re: [SciPy-dev] Doc-ing classes and data attributes > To: "SciPy Developers List" <scipy-dev(a)scipy.org> > Date: Sunday, June 21, 2009, 7:32 AM > 2009/6/21 Ralf Gommers <ralf.gommers(a)googlemail.com>: > > The CodingStyleGuidelines page is generated from > > /trunk/doc/HOWTO_DOCUMENT.txt so editing on Trac is > not what you want. The > > page is already in reST format, so can we add it to > the doc editor and edit > > it there? > > The documentation standard should not be open to > editing. You are, of > course, welcome to provide patches that we can apply after > discussion, > but this document cannot be in a state of flux. > > Regards > Stéfan > _______________________________________________ > Scipy-dev mailing list > Scipy-dev(a)scipy.org > http://mail.scipy.org/mailman/listinfo/scipy-dev >

2 1

Re: [SciPy-dev] Doc-ing classes and data attributes
by David Goldsmith June 21, 2009

June 21, 2009

--- On Sat, 6/20/09, Ralf Gommers <ralf.gommers(a)googlemail.com> wrote: <big snip> > > Look at ndarray for an example: http://docs.scipy.org/numpy/docs/numpy.ndarray/#numpy-ndarray > > > Documenting the class indeed means its __init__ > > > function as far as Parameters, See Also, Examples, > etc. This > > > is what has been done so far for all classes I've > looked > > > at. > > > The Methods and Attributes sections show up > automatically, > > > and contain all public methods/attributes, so > don't > > > worry about putting a list of those in. Those > > > methods/attributes do have their own docstrings. > > If I may have edit privileges at http://projects.scipy.org/numpy/wiki/ > I can add these clarifications there myself; otherwise, > I'll file a ticket at pydocweb. > > The CodingStyleGuidelines page is generated from > /trunk/doc/HOWTO_DOCUMENT.txt so editing on Trac is not what > you want. The page is already in reST format, so can we add > it to the doc editor and edit it there? > > I'd like to be able to make changes to it as well, a Glad to see I'm not the only one. ;-) > few I can think of right away are > - documenting class instances > - documenting constants > - the [out] parameter Regarding this last, as per a suggestion from Pauli in the Discussion following ndarray.rst, I just now finished adding a "See also, numpy.doc.ufuncs, 'Output arguments' section" to the ndarray methods possessing the [out] parameter (actually, I added it to the docstrings of their equivalent functions outside of the ndarray namespace), so keep this in mind when contemplating what to add in the HOWTO_DOCUMENT.txt. :-) DG > Ralf > > > > > -----Inline Attachment Follows----- > > _______________________________________________ > Scipy-dev mailing list > Scipy-dev(a)scipy.org > http://mail.scipy.org/mailman/listinfo/scipy-dev >

1 0

Re: [SciPy-dev] Doc-ing classes and data attributes
by David Goldsmith June 21, 2009

June 21, 2009

Excellent, Ralf, thanks! DG --- On Sat, 6/20/09, Ralf Gommers <ralf.gommers(a)googlemail.com> wrote: > From: Ralf Gommers <ralf.gommers(a)googlemail.com> > Subject: Re: [SciPy-dev] Doc-ing classes and data attributes > To: "SciPy Developers List" <scipy-dev(a)scipy.org> > Date: Saturday, June 20, 2009, 5:46 PM > > > On Sat, Jun 20, 2009 at 8:41 PM, > David Goldsmith <d_l_goldsmith(a)yahoo.com> > wrote: > > > > Thanks, Pierre, this is helpful, but the given example > doesn't have any of the _other_ sections Functions have, > though the docstring standard says "all but Returns are > relevant," so I'm left wondering where to insert > the "new" sections relative to the > "old." (I know that not _all_ Function sections > will always be relevant for _all_ classes, but I assume at > least some of them will be relevant for some classes, but > your example doesn't clarify where to put them.) But, > FWIW, thanks. > > > > > Look at ndarray for an example: http://docs.scipy.org/numpy/docs/numpy.ndarray/#numpy-ndarray > > Documenting the class indeed means its __init__ > function as far as Parameters, See Also, Examples, etc. This > is what has been done so far for all classes I've looked > at. > > > > The Methods and Attributes sections show up automatically, > and contain all public methods/attributes, so don't > worry about putting a list of those in. Those > methods/attributes do have their own docstrings. > > Cheers, > > Ralf > > > > > DG > > > > --- On Sat, 6/20/09, Pierre GM <pgmdevlist(a)gmail.com> > wrote: > > > > > From: Pierre GM <pgmdevlist(a)gmail.com> > > > Subject: Re: [SciPy-dev] Doc-ing > classes and data attributes > > > To: "SciPy Developers List" <scipy-dev(a)scipy.org> > > > Date: Saturday, June 20, 2009, 5:06 PM > > > > > > On Jun 20, 2009, at 7:23 PM, David Goldsmith wrote: > > > > > > > > > > > Ok, a couple follow-up questions: where > precisely > > > should > > > > documentation of __init__, and the Attributes > and > > > Methods sections > > > > (when needed) go? In other words, > > > docstringstandard says, "Use the > > > > same sections as outlined [for Functions]," > but as > > > Functions don't > > > > have __init__, Attributes, or Methods, it is > unclear > > > where in the > > > > "above" template these new items should > go. > > > > > > My 2c: > > > > > > * I don't document __init__, but I put a > 'Parameters' > > > section in the > > > docstring of the class that describes all the input > > > parameters of > > > __init__ > > > * Methods could be described in the docstring of the > class, > > > under a > > > 'Methods' entry, but it might be more > appropriate to > > > document them > > > outside the class. > > > * Same thing for Attributes: you could have a small > list in > > > the > > > docstring, but as soon as you start documenting an > > > attribute in > > > detail, you'd better have a separate section. > > > > > > Check http://pytseries.sourceforge.net/core.timeseries.html > > > for an > > > example of application. > > > > > > > > > _______________________________________________ > > > Scipy-dev mailing list > > > Scipy-dev(a)scipy.org > > > http://mail.scipy.org/mailman/listinfo/scipy-dev > > > > > > > > > > > _______________________________________________ > > Scipy-dev mailing list > > Scipy-dev(a)scipy.org > > http://mail.scipy.org/mailman/listinfo/scipy-dev > > > > > -----Inline Attachment Follows----- > > _______________________________________________ > Scipy-dev mailing list > Scipy-dev(a)scipy.org > http://mail.scipy.org/mailman/listinfo/scipy-dev >

1 0

Re: [SciPy-dev] Doc-ing classes and data attributes
by David Goldsmith June 21, 2009

June 21, 2009

Thanks, Pierre, this is helpful, but the given example doesn't have any of the _other_ sections Functions have, though the docstring standard says "all but Returns are relevant," so I'm left wondering where to insert the "new" sections relative to the "old." (I know that not _all_ Function sections will always be relevant for _all_ classes, but I assume at least some of them will be relevant for some classes, but your example doesn't clarify where to put them.) But, FWIW, thanks. DG --- On Sat, 6/20/09, Pierre GM <pgmdevlist(a)gmail.com> wrote: > From: Pierre GM <pgmdevlist(a)gmail.com> > Subject: Re: [SciPy-dev] Doc-ing classes and data attributes > To: "SciPy Developers List" <scipy-dev(a)scipy.org> > Date: Saturday, June 20, 2009, 5:06 PM > > On Jun 20, 2009, at 7:23 PM, David Goldsmith wrote: > > > > > Ok, a couple follow-up questions: where precisely > should > > documentation of __init__, and the Attributes and > Methods sections > > (when needed) go? In other words, > docstringstandard says, "Use the > > same sections as outlined [for Functions]," but as > Functions don't > > have __init__, Attributes, or Methods, it is unclear > where in the > > "above" template these new items should go. > > My 2c: > > * I don't document __init__, but I put a 'Parameters' > section in the > docstring of the class that describes all the input > parameters of > __init__ > * Methods could be described in the docstring of the class, > under a > 'Methods' entry, but it might be more appropriate to > document them > outside the class. > * Same thing for Attributes: you could have a small list in > the > docstring, but as soon as you start documenting an > attribute in > detail, you'd better have a separate section. > > Check http://pytseries.sourceforge.net/core.timeseries.html > for an > example of application. > > > _______________________________________________ > Scipy-dev mailing list > Scipy-dev(a)scipy.org > http://mail.scipy.org/mailman/listinfo/scipy-dev >

2 1

Re: [SciPy-dev] Doc-ing classes and data attributes
by David Goldsmith June 21, 2009

June 21, 2009

Ok, a couple follow-up questions: where precisely should documentation of __init__, and the Attributes and Methods sections (when needed) go? In other words, docstringstandard says, "Use the same sections as outlined [for Functions]," but as Functions don't have __init__, Attributes, or Methods, it is unclear where in the "above" template these new items should go. Also, since __init__ is a method, I assume it should itself be documented like any other method, i.e., w/ a definition, one line desc., multi-line desc., parameters section, etc. To my mind, to avoid clutter and excessively long docstrings, it seems like it should be documented separately; but then perhaps what is meant is that documenting the class is really documenting its __init__? Thanks, DG --- On Fri, 6/19/09, Stéfan van der Walt <stefan(a)sun.ac.za> wrote: > From: Stéfan van der Walt <stefan(a)sun.ac.za> > Subject: Re: [SciPy-dev] Doc-ing classes and data attributes > To: "SciPy Developers List" <scipy-dev(a)scipy.org> > Date: Friday, June 19, 2009, 11:19 PM > Hi David > > 2009/6/20 David Goldsmith <d_l_goldsmith(a)yahoo.com>: > > Hi! The template http://projects.scipy.org/numpy/browser/trunk/doc/example.py#L37 > for documenting things doesn't seem like a very good > template for documenting objects, e.g., ufunc, and data (as > opposed to method) attributes of objects, e.g., > ndarray.dtype. Are there other templates for these > elsewhere? Thanks! > > Have a look at > > http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines#docstring-standa… > > under the section "Documenting Classes". Is that what > you're looking for? > > Regards > Stéfan > _______________________________________________ > Scipy-dev mailing list > Scipy-dev(a)scipy.org > http://mail.scipy.org/mailman/listinfo/scipy-dev >

3 2