Re: [Numpy-discussion] ANN: NumPy/SciPy Documentation Marathon 2008
On Samstag 17 Mai 2008, Joe Harrington wrote: > To head off another pedagogical meltdown, the University of Central > Florida has hired Stefan van der Walt full time to coordinate a > community documentation effort to write reference documentation and > tools. This is truly excellent news. One question though: I didn't see Travis's Numpy book mentioned at all in your writeup, so I am wondering where its role in the doc effort is. Its home page states that it will be opened on Sep 1, 2008, apparently in time for classes, and it already provides parts of what you propose. Mainly: while we need to respect Travis's copyright, a duplication of the massive effort that went into the book hardly seems sensible. One initial question is therefore: Is it OK to copy material out of the book and into other parts of the documentation? Andreas signature.asc Description: This is a digitally signed message part. ___ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] ANN: NumPy/SciPy Documentation Marathon 2008
Hi Andreas 2008/5/17 Andreas Klöckner <[EMAIL PROTECTED]>: > On Samstag 17 Mai 2008, Joe Harrington wrote: >> To head off another pedagogical meltdown, the University of Central >> Florida has hired Stefan van der Walt full time to coordinate a >> community documentation effort to write reference documentation and >> tools. > > This is truly excellent news. One question though: I didn't see Travis's Numpy > book mentioned at all in your writeup, so I am wondering where its role in > the doc effort is. Its home page states that it will be opened on Sep 1, > 2008, apparently in time for classes, and it already provides parts of what > you propose. Travis has generously pemitted us to use any part of his book in the documentation. We shall be making use of his kind offer! As far as I am aware, the code to his book will be released at SciPy 2008 (http://conference.scipy.org). Regards Stéfan ___ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] ANN: NumPy/SciPy Documentation Marathon 2008
> I didn't see Travis's Numpy book mentioned at all in your writeup, so > I am wondering where its role in the doc effort is. > Is it OK to copy material out of the book and into > other parts of the documentation? No worries, Travis is on board here. We included him and others on the Steering Committee in planning this effort. Travis's book overlaps the current effort to some extent. The function descriptions in the book are the numpy docstrings, such as they currently exist. The docstrings are open source software and the book is a work derived from them. The current effort is essentially to fill in the docstrings to the full expectation of professional reference documentation. If you compare the docstring example on the wiki (for multivariate_normal) with the current page for that function, you'll see the difference. The multivariate_normal docstring is actually pretty good among current docstrings, but even for this function we're aiming for a big change. Collected, the new docstrings will make a reference manual very much like those you'll find for other scientific languages, with similar format for the pages. The choice of a ReST-based docstring format some time ago was to support producing such a manual. The rest of Travis's book is still critical information and we're not contemplating replacing it at this point. Much of it is on the technical end, and our goal is to address the general user, particularly students learning to do data analysis, so I think even the eventual User Guide, whatever form it takes, will not encroach on its technical focus. Of course, he's welcome to include the improved docstrings in his book if he wants to (as is anyone), or to exclude them and make a tighter book aimed at extension programmers, or whatever. Let's continue discussion on scipy-dev, just to keep it all in one place. --jh-- ___ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] ANN: NumPy/SciPy Documentation Marathon 2008
Joe Harrington wrote: > NUMPY/SCIPY DOCUMENTATION MARATHON 2008 > ... > 5. Write a new help function that optionally produces ASCII or points > the user's PDF or HTML reader to the right page (either local or > global). > I can work on this. Fernando suggested this at the IPython sprint in Boulder last year, so I've given it some thought and started a wiki page: http://ipython.scipy.org/moin/Developer_Zone/SearchDocs Regards, Steve ___ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] ANN: NumPy/SciPy Documentation Marathon 2008
Hi, su, 2008-05-18 kello 07:16 -0600, Steven H. Rogers kirjoitti: > Joe Harrington wrote: > >NUMPY/SCIPY DOCUMENTATION MARATHON 2008 > > ... > > 5. Write a new help function that optionally produces ASCII or points > > the user's PDF or HTML reader to the right page (either local or > > global). > > > I can work on this. Fernando suggested this at the IPython sprint in > Boulder last year, so I've given it some thought and started a wiki page: > http://ipython.scipy.org/moin/Developer_Zone/SearchDocs In Numpy SVN/1.1 there is a function "lookfor" that searches the docstrings for a substring (no stemming etc. is done). Similar "%lookfor" magic command got accepted into IPython0 as an extension ipy_lookfor.py. Improvements to these would be surely appreciated. I think that also Sphinx supports searching, so that the generated HTML docs [1] are searchable, as is the generated PDF output. Pauli .. [1] http://mentat.za.net/numpy/refguide/ So far, this preview contains only docs for ndarray, though. ___ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] ANN: NumPy/SciPy Documentation Marathon 2008
Pauli Virtanen wrote: > Hi, > > su, 2008-05-18 kello 07:16 -0600, Steven H. Rogers kirjoitti: > >> Joe Harrington wrote: >> >>>NUMPY/SCIPY DOCUMENTATION MARATHON 2008 >>> ... >>> 5. Write a new help function that optionally produces ASCII or points >>> the user's PDF or HTML reader to the right page (either local or >>> global). >>> >>> >> I can work on this. Fernando suggested this at the IPython sprint in >> Boulder last year, so I've given it some thought and started a wiki page: >> http://ipython.scipy.org/moin/Developer_Zone/SearchDocs >> > > In Numpy SVN/1.1 there is a function "lookfor" that searches the > docstrings for a substring (no stemming etc. is done). Similar > "%lookfor" magic command got accepted into IPython0 as an extension > ipy_lookfor.py. Improvements to these would be surely appreciated. > > I think that also Sphinx supports searching, so that the generated HTML > docs [1] are searchable, as is the generated PDF output. > > Pauli > > > .. [1] http://mentat.za.net/numpy/refguide/ >So far, this preview contains only docs for ndarray, though. > > Thanks Pauli. Looking at these. # Steve ___ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] ANN: NumPy/SciPy Documentation Marathon 2008
2008/5/20 Steven H. Rogers <[EMAIL PROTECTED]>: >> .. [1] http://mentat.za.net/numpy/refguide/ >>So far, this preview contains only docs for ndarray, though. The reference guide has been updated to contain the entire numpy. Once we've applied indexing tags to functions, those will be sorted in a more coherent manner. Also, the math role and directive, i.e. :math:`\int_0^\infty` and .. math:: \int_0^\infty now render correctly. This is achieved using mathml in the xhtml files (so you need to install a mathml plugin if you use Internet Explorer). For en example, see "bartlett" (use the index to find it, quicksearch is currently broken). Regards Stéfan ___ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] ANN: NumPy/SciPy Documentation Marathon 2008
On Tue, 20 May 2008, Stéfan van der Walt apparently wrote: > Also, the math role and directive, i.e. > :math:`\int_0^\infty` and > .. math:: \int_0^\infty > now render correctly. Is this being done with Jens's writers? If not, I'd like to know how. Thank you, Alan Isaac PS There is currently active discussion by the docutils developers about implementing moving the math role and directive into docutils. Discovered issues could be usefully shared right now! ___ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] ANN: NumPy/SciPy Documentation Marathon 2008
Hi Alan Yes, the one discussed in this thread: http://groups.google.com/group/sphinx-dev/browse_thread/thread/ef74352b9f196002/0e257bc8c116f73f I've only had to make one change so far, to parse '*' as in 'A^*' (patch attached). Unfortunately, the author chose incomprehensible variable names like 'mo', 'mi', and 'mn', so I'm not sure I fixed it the right way. I'd be very glad if these directives became part of docutils -- I'd be glad if you could monitor that situation for us. Regards Stéfan 2008/5/20 Alan G Isaac <[EMAIL PROTECTED]>: > On Tue, 20 May 2008, Stéfan van der Walt apparently wrote: >> Also, the math role and directive, i.e. >> :math:`\int_0^\infty` and >> .. math:: \int_0^\infty >> now render correctly. > > Is this being done with Jens's writers? > If not, I'd like to know how. > > Thank you, > Alan Isaac > > PS There is currently active discussion by the docutils > developers about implementing moving the math role and > directive into docutils. Discovered issues could be > usefully shared right now! mathml.patch Description: Binary data ___ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] ANN: NumPy/SciPy Documentation Marathon 2008
I would like to help, but it's not clear to me exactly how to do that from the wiki. What are the steps? -Rob ___ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] ANN: NumPy/SciPy Documentation Marathon 2008
Hi Rob Which of the instructions are not clear? We'd like to make this as accessible as possible. In order to start editing, you need to complete step 5, which is to register on the wiki and send us your UserName. Regards Stéfan 2008/5/20 Rob Hetland <[EMAIL PROTECTED]>: > > I would like to help, but it's not clear to me exactly how to do that > from the wiki. What are the steps? > > -Rob ___ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] ANN: NumPy/SciPy Documentation Marathon 2008
Joe Harrington wrote: > NUMPY/SCIPY DOCUMENTATION MARATHON 2008 > On the wiki it says: "Writers should be fluent in English" In case someone is working on the dynamic docstring magic, is this a good moment to mention "internationalisation" and "world domination" in the same sentence? -Jon ___ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] ANN: NumPy/SciPy Documentation Marathon 2008
On May 20, 2008, at 7:30 PM, Stéfan van der Walt wrote: > ...and send us your UserName. This is the part I skipped over... I registered, and wondered why everything was not editable. -Rob Rob Hetland, Associate Professor Dept. of Oceanography, Texas A&M University http://pong.tamu.edu/~rob phone: 979-458-0096, fax: 979-845-6331 ___ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] ANN: NumPy/SciPy Documentation Marathon 2008
On May 20, 2008, at 7:30 PM, Stéfan van der Walt wrote: > and send us your UserName. Oh, and my username is RobHetland -Rob Rob Hetland, Associate Professor Dept. of Oceanography, Texas A&M University http://pong.tamu.edu/~rob phone: 979-458-0096, fax: 979-845-6331 ___ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] ANN: NumPy/SciPy Documentation Marathon 2008
ti, 2008-05-20 kello 20:06 +0200, Rob Hetland kirjoitti: > On May 20, 2008, at 7:30 PM, Stéfan van der Walt wrote: > > > and send us your UserName. > > > Oh, and my username is RobHetland You're in now. Regards, Pauli ___ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] ANN: NumPy/SciPy Documentation Marathon 2008
2008/5/20 Jonathan Wright <[EMAIL PROTECTED]>: > Joe Harrington wrote: >> NUMPY/SCIPY DOCUMENTATION MARATHON 2008 >> > On the wiki it says: "Writers should be fluent in English" > > In case someone is working on the dynamic docstring magic, is this a > good moment to mention "internationalisation" and "world domination" in > the same sentence? I think we'll stick to English for now (I don't think I have the motivation to do an Afrikaans translation!). As for internationali(s/z)ation, we'll see who writes the most docstrings. In a fortuitous twist of events, I find myself able to read American as well :) Cheers Stéfan ___ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] ANN: NumPy/SciPy Documentation Marathon 2008
Stéfan van der Walt wrote: > As for internationali(s/z)ation, we'll see who writes the most > docstrings. Indeed. There are some notes on the OLPC wiki at http://wiki.laptop.org/go/Python_i18n It seems to be just a question of adding at the top of add_newdocs.py from gettext import gettext as _ ... and putting the docstrings in a _() function call, although perhaps I miss something important, like a performance hit? This would catch everything in add_newdocs at least. It seems like a relatively minor change if you are overhauling anyway? Jon ___ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] ANN: NumPy/SciPy Documentation Marathon 2008
On Tue, May 20, 2008 at 5:55 PM, Jonathan Wright <[EMAIL PROTECTED]> wrote: > Stéfan van der Walt wrote: > > As for internationali(s/z)ation, we'll see who writes the most > > docstrings. > > Indeed. There are some notes on the OLPC wiki at > > http://wiki.laptop.org/go/Python_i18n > > It seems to be just a question of adding at the top of add_newdocs.py > > from gettext import gettext as _ > > ... and putting the docstrings in a _() function call, although perhaps > I miss something important, like a performance hit? Possibly a significant one. This could affect startup times, which I am hesitant to make worse. > This would catch > everything in add_newdocs at least. It seems like a relatively minor > change if you are overhauling anyway? add_newdocs() could do that, but the usual function docstrings can't. The rule is that if the first statement in a function is a literal string, then the compiler will assign it func.__doc__. Expressions are just treated as expressions in the function body and have no affect on func.__doc__. -- 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 ___ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] ANN: NumPy/SciPy Documentation Marathon 2008
ti, 2008-05-20 kello 18:04 -0500, Robert Kern kirjoitti: > On Tue, May 20, 2008 at 5:55 PM, Jonathan Wright <[EMAIL PROTECTED]> wrote: > > Stéfan van der Walt wrote: > > > As for internationali(s/z)ation, we'll see who writes the most > > > docstrings. > > > > Indeed. There are some notes on the OLPC wiki at > > > > http://wiki.laptop.org/go/Python_i18n > > > > It seems to be just a question of adding at the top of add_newdocs.py > > > > from gettext import gettext as _ > > > > ... and putting the docstrings in a _() function call, although perhaps > > I miss something important, like a performance hit? > > Possibly a significant one. This could affect startup times, which I > am hesitant to make worse. > > > This would catch > > everything in add_newdocs at least. It seems like a relatively minor > > change if you are overhauling anyway? > > add_newdocs() could do that, but the usual function docstrings can't. > The rule is that if the first statement in a function is a literal > string, then the compiler will assign it func.__doc__. Expressions are > just treated as expressions in the function body and have no affect on > func.__doc__. I think it would be quite straightforward to write a function that crawled over the numpy namespace and dynamically replaced __doc__ with gettextized versions. The user could call this function to switch the language and the reference manual authors could call it to produce localized versions of the manual. Moreover, we already have tools to extract English docstrings from numpy and producing .pot files for gettext could be done. I think i18n of numpy (or any other Python module) is technically not as far out as it initially seems! (This is assuming that there are no objects there that don't allow changing their __doc__.) But I believe that in practice, we really had better to concentrate on improving the documentation in English before thinking about spending much effort on i18n or l10n. -- Pauli Virtanen ___ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] ANN: NumPy/SciPy Documentation Marathon 2008
On Wed, May 21, 2008 at 1:27 AM, Pauli Virtanen <[EMAIL PROTECTED]> wrote: > I think it would be quite straightforward to write a function that > crawled over the numpy namespace and dynamically replaced __doc__ with > gettextized versions. The user could call this function to switch the > language and the reference manual authors could call it to produce > localized versions of the manual. Moreover, we already have tools to > extract English docstrings from numpy and producing .pot files for > gettext could be done. I think i18n of numpy (or any other Python > module) is technically not as far out as it initially seems! Yes, that sounds (technically) feasible. > (This is assuming that there are no objects there that don't allow > changing their __doc__.) > > But I believe that in practice, we really had better to concentrate on > improving the documentation in English before thinking about spending > much effort on i18n or l10n. Yup. Sounds about right. -- 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 ___ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] ANN: NumPy/SciPy Documentation Marathon 2008
Should we add a general discussion section to the Wiki? I would just do this, but it seems like a fundamental enough addition that I though I would suggest it first. The rational is that there are some stylistic questions that are not covered in the example. For instance, I think that the See Also section should have a format like this: See Also function : One line description from function's docstring Longer description here over potentially many lines. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. next_function : One line description from next_function's docstring Longer description here over potentially many lines. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. This will parse better (as the line with the semicolon is bold, the next lines are not). Also, would it be possible to put function and next_function in double back-ticks, so that they are referenced, like modules? That way they will might be clickable in a html version of the documentation. -Rob ___ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] ANN: NumPy/SciPy Documentation Marathon 2008
On Wed, May 21, 2008 at 2:27 AM, Rob Hetland <[EMAIL PROTECTED]> wrote: > > Should we add a general discussion section to the Wiki? Discussion should happen here on the mailing list instead of the wiki. But please, let's not rehash discussions which have already happened (like this one). They simply have no way of coming to a conclusion and cannot improve matters enough to justify the effort expended on the discussion. -- 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 ___ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] ANN: NumPy/SciPy Documentation Marathon 2008
Hi Rob 2008/5/21 Rob Hetland <[EMAIL PROTECTED]>: > See Also > > function : One line description from function's docstring > Longer description here over potentially many lines. Lorem ipsum > dolor sit amet, > consectetur adipisicing elit, sed do eiusmod tempor incididunt ut > labore et dolore > magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation > ullamco laboris nisi > ut aliquip ex ea commodo consequat. > next_function : One line description from next_function's docstring > Longer description here over potentially many lines. Lorem ipsum > dolor sit amet, > consectetur adipisicing elit, sed do eiusmod tempor incididunt ut > labore et dolore > magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation > ullamco laboris nisi > ut aliquip ex ea commodo consequat. > > > This will parse better (as the line with the semicolon is bold, the > next lines are not). Also, would it be possible to put function and > next_function in double back-ticks, so that they are referenced, like > modules? That way they will might be clickable in a html version of > the documentation. When generating the reference guide, I parse all the numpy docstrings and re-generate a document enhanced with Sphinx markup. In this document, functions in the See Also clause are "clickable". I have support for two formats: See Also function_a, function_b, function_c function_d : relation to current function Don't worry if it doesn't look perfect on the wiki; the reference guide will be rendered correctly. Regards Stéfan ___ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] ANN: NumPy/SciPy Documentation Marathon 2008
On May 21, 2008, at 9:40 AM, Robert Kern wrote: > But please, let's not rehash discussions which have already happened > (like this one). I didn't mean to suggest rehashing the documentation format. I agree that this has been discussed enough. Rather, sometimes it's not clear to me how to apply the existing standard. 'See Also' was a case where the style guidelines seem sparse. My suggestion, I guess, was more to clarify than to change. -Rob Rob Hetland, Associate Professor Dept. of Oceanography, Texas A&M University http://pong.tamu.edu/~rob phone: 979-458-0096, fax: 979-845-6331 ___ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] ANN: NumPy/SciPy Documentation Marathon 2008
Hi, I would like to throw out the following idea with no obligations: IF people have the time and energy while writing the documentation, can they also test that the function is doing what it is expected? Also related to this is developing appropriate tests if these are not covered or at least provide a file of code used in evaluating the functionality. The precedence for this that a number of Linux kernel bugs have been identified this way. Thanks Bruce ___ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] ANN: NumPy/SciPy Documentation Marathon 2008
Hi Bruce 2008/5/21 Bruce Southey <[EMAIL PROTECTED]>: > I would like to throw out the following idea with no obligations: > IF people have the time and energy while writing the documentation, can > they also test that the function is doing what it is expected? > Also related to this is developing appropriate tests if these are not > covered or at least provide a file of code used in evaluating the > functionality. We are adding examples (read: doctests) to every function, which serve as unit tests at the same time. In writing these, we do come across bugs (like http://projects.scipy.org/scipy/numpy/ticket/798), for which tickets are filed. This is a documentation drive, though, so the examples are illustrative; we don't aim to write exhaustive unit tests that cover all corner cases. That said, any person who wishes to contribute unit tests is most welcome to do so. I can guarantee that your patches will be applied speedily :) Regards Stéfan ___ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] ANN: NumPy/SciPy Documentation Marathon 2008
Stéfan van der Walt wrote: > Hi Bruce > > 2008/5/21 Bruce Southey <[EMAIL PROTECTED]>: > >> I would like to throw out the following idea with no obligations: >> IF people have the time and energy while writing the documentation, can >> they also test that the function is doing what it is expected? >> Also related to this is developing appropriate tests if these are not >> covered or at least provide a file of code used in evaluating the >> functionality. >> > > We are adding examples (read: doctests) to every function, which serve > as unit tests at the same time. In writing these, we do come across > bugs (like http://projects.scipy.org/scipy/numpy/ticket/798), for > which tickets are filed. This is a documentation drive, though, so > the examples are illustrative; we don't aim to write exhaustive unit > tests that cover all corner cases. > > That said, any person who wishes to contribute unit tests is most > welcome to do so. I can guarantee that your patches will be applied > speedily :) > > Regards > Stéfan > ___ > Numpy-discussion mailing list > Numpy-discussion@scipy.org > http://projects.scipy.org/mailman/listinfo/numpy-discussion > > Hi Excellent as I did not see any mention of this on the web page. Bruce ___ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] ANN: NumPy/SciPy Documentation Marathon 2008
On Wed, May 21, 2008 at 3:26 AM, Rob Hetland <[EMAIL PROTECTED]> wrote: > > On May 21, 2008, at 9:40 AM, Robert Kern wrote: > >> But please, let's not rehash discussions which have already happened >> (like this one). > > I didn't mean to suggest rehashing the documentation format. I agree > that this has been discussed enough. > > Rather, sometimes it's not clear to me how to apply the existing > standard. 'See Also' was a case where the style guidelines seem > sparse. My suggestion, I guess, was more to clarify than to change. Okey-dokey. -- 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 ___ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] ANN: NumPy/SciPy Documentation Marathon 2008
This is really a great news, and it seems very promising according to the first pages of the Wiki that I've seen. It's perhaps not the right place to say this, but I was wondering what you would thinking about adding labels or category to the descriptions of each function ? I think It would really help newcomers to search around the 400 functions of numpy if they could use some labels to precise theirs thoughts. Until now, the most efficient why of finding the numpy function that fits my needds what to search after some words in the numpy example list page. This was not always very fast and labels like "array creation", "shape manipulation","index operation", "arithmetic", ...etc, could simplify this kind of search. -- LB ___ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] ANN: NumPy/SciPy Documentation Marathon 2008
2008/5/21 LB <[EMAIL PROTECTED]>: > This is really a great news, and it seems very promising according to > the first pages of the Wiki that I've seen. > > It's perhaps not the right place to say this, but I was wondering what > you would thinking about adding labels or category to the descriptions > of each function ? I think It would really help newcomers to search > around the 400 functions of numpy if they could use some labels to > precise theirs thoughts. You're right that some kind of categorization would be very valuable. I think that this is planned, but the doc marathon organizers can presumably give a more detailed answer. > Until now, the most efficient why of finding the numpy function that > fits my needds what to search after some words in the numpy example > list page. This was not always very fast and labels like "array > creation", "shape manipulation","index operation", > "arithmetic", ...etc, could simplify this kind of search. In the short term, there's the numpy functions by category page on the wiki: http://www.scipy.org/Numpy_Functions_by_Category Of course, this page is already incomplete, and nobody is systematically updating it. Really the right solution is what you propose, annotating each function and then automatically generating such a list. Anne ___ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] ANN: NumPy/SciPy Documentation Marathon 2008
Hi LB 2008/5/21 LB <[EMAIL PROTECTED]>: > This is really a great news, and it seems very promising according to > the first pages of the Wiki that I've seen. > > It's perhaps not the right place to say this, but I was wondering what > you would thinking about adding labels or category to the descriptions > of each function ? I think It would really help newcomers to search > around the 400 functions of numpy if they could use some labels to > precise theirs thoughts. If you take a look at the new docstring standard, we've introduced a new `index` tag, that can be used as follows: .. index:: :refguide: trigonometry, ufunc We still need to decide on which categories to use, but the markup is there. > Until now, the most efficient why of finding the numpy function that > fits my needds what to search after some words in the numpy example > list page. This was not always very fast and labels like "array > creation", "shape manipulation","index operation", > "arithmetic", ...etc, could simplify this kind of search. Watch this space! Cheers Stéfan ___ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] ANN: NumPy/SciPy Documentation Marathon 2008
ke, 2008-05-21 kello 10:08 +0200, Stéfan van der Walt kirjoitti: [clip] > > This will parse better (as the line with the semicolon is bold, the > > next lines are not). Also, would it be possible to put function and > > next_function in double back-ticks, so that they are referenced, like > > modules? That way they will might be clickable in a html version of > > the documentation. > > When generating the reference guide, I parse all the numpy docstrings > and re-generate a document enhanced with Sphinx markup. In this > document, functions in the See Also clause are "clickable". I have > support for two formats: > > See Also > > function_a, function_b, function_c > function_d : relation to current function > > Don't worry if it doesn't look perfect on the wiki; the reference > guide will be rendered correctly. Should the function names in the See also section also include the namespace prefix, ie. numpy.function_a numpy.function_b Or should we "assume from numpy import *" or "import numpy as np"? I think it'd be useful to clarify this in the documentation standard and in example.py, also for the Examples section. (Btw, the Docstrings/Example appears to be out-of-date wrt. this.) Pauli ___ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] ANN: NumPy/SciPy Documentation Marathon 2008
On May 22, 2008, at 11:37 AM, Pauli Virtanen wrote: > Or should we "assume from numpy import *" or "import numpy as np"? I Although a good case could probably be made for all three (*, np, numpy), I think that if "import numpy as np" is to be put forward as the standard coding style, the examples should use this as well. -Rob Rob Hetland, Associate Professor Dept. of Oceanography, Texas A&M University http://pong.tamu.edu/~rob phone: 979-458-0096, fax: 979-845-6331 ___ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] ANN: NumPy/SciPy Documentation Marathon 2008
It looks like there is significant interest in using "np" instead of "numpy" in the examples (i.e. we expect the user to do "import numpy as np" before trying code snippets). Would anybody who objects to using "np" raise it now, so that we can bury this issue? Regards Stéfan 2008/5/22 Rob Hetland <[EMAIL PROTECTED]>: > > On May 22, 2008, at 11:37 AM, Pauli Virtanen wrote: > >> Or should we "assume from numpy import *" or "import numpy as np"? I > > > Although a good case could probably be made for all three (*, np, > numpy), I think that if "import numpy as np" is to be put forward as > the standard coding style, the examples should use this as well. > > -Rob > > > Rob Hetland, Associate Professor > Dept. of Oceanography, Texas A&M University > http://pong.tamu.edu/~rob > phone: 979-458-0096, fax: 979-845-6331 > > > > ___ > Numpy-discussion mailing list > Numpy-discussion@scipy.org > http://projects.scipy.org/mailman/listinfo/numpy-discussion > ___ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] ANN: NumPy/SciPy Documentation Marathon 2008
Stéfan van der Walt wrote: > It looks like there is significant interest in using "np" instead of > "numpy" in the examples (i.e. we expect the user to do "import numpy > as np" before trying code snippets). > > Would anybody who objects to using "np" raise it now, so that we can > bury this issue? > > Regards > Stéfan > > 2008/5/22 Rob Hetland <[EMAIL PROTECTED]>: > >> On May 22, 2008, at 11:37 AM, Pauli Virtanen wrote: >> >> >>> Or should we "assume from numpy import *" or "import numpy as np"? I >>> >> Although a good case could probably be made for all three (*, np, >> numpy), I think that if "import numpy as np" is to be put forward as >> the standard coding style, the examples should use this as well. >> >> -Rob >> >> >> Rob Hetland, Associate Professor >> Dept. of Oceanography, Texas A&M University >> http://pong.tamu.edu/~rob >> phone: 979-458-0096, fax: 979-845-6331 >> >> >> >> ___ >> Numpy-discussion mailing list >> Numpy-discussion@scipy.org >> http://projects.scipy.org/mailman/listinfo/numpy-discussion >> >> > ___ > Numpy-discussion mailing list > Numpy-discussion@scipy.org > http://projects.scipy.org/mailman/listinfo/numpy-discussion > > Hi, I prefer using 'import numpy' over 'import numpy as np'. But as long as each example has 'import numpy as np' included then I have no objections. The main reason for this is that the block of code can easily be copied and pasted to run a complete entity. Also this type of implicit assumption often get missed because these assumptions are often far from the example (missed in web searches) or overlooked as the reader doesn't think that part was important. Regards Bruce ___ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion
