# ANN: NumPy/SciPy Documentation Marathon 2008

37 messages
12
Open this post in threaded view
|

## ANN: NumPy/SciPy Documentation Marathon 2008

Open this post in threaded view
|

## Re: [SciPy-user] ANN: NumPy/SciPy Documentation Marathon 2008

 Ryan writes: > This is very good news.  I will find some way to get involved. Great!  Please dive right in, and sign up on the Developer_Zone page so we can keep track of who's involved. One thing I forgot to mention in my too-wordy announcement was that discussion of documentation is on the scipy-dev mailing list.  We had to pick one spot and decided that since we are going after scipy as soon as numpy is done, we'd like to use that list rather than numpy-discussion.  We also wanted to keep it on a development list rather than polluting the new users' discussion space. --jh-- _______________________________________________ Numpy-discussion mailing list [hidden email] http://projects.scipy.org/mailman/listinfo/numpy-discussion
Open this post in threaded view
|

## Re: ANN: NumPy/SciPy Documentation Marathon 2008

 In reply to this post by Joe Harrington 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 _______________________________________________ Numpy-discussion mailing list [hidden email] http://projects.scipy.org/mailman/listinfo/numpy-discussion signature.asc (196 bytes) Download Attachment
Open this post in threaded view
|

## Re: ANN: NumPy/SciPy Documentation Marathon 2008

 Hi Andreas 2008/5/17 Andreas Klöckner <[hidden email]>: > 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 [hidden email] http://projects.scipy.org/mailman/listinfo/numpy-discussion
Open this post in threaded view
|

## Re: ANN: NumPy/SciPy Documentation Marathon 2008

 In reply to this post by Joe Harrington > 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 [hidden email] http://projects.scipy.org/mailman/listinfo/numpy-discussion
Open this post in threaded view
|

## Re: ANN: NumPy/SciPy Documentation Marathon 2008

 In reply to this post by Joe Harrington 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/SearchDocsRegards, Steve _______________________________________________ Numpy-discussion mailing list [hidden email] http://projects.scipy.org/mailman/listinfo/numpy-discussion
Open this post in threaded view
|

## Re: 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/SearchDocsIn 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 [hidden email] http://projects.scipy.org/mailman/listinfo/numpy-discussion
Open this post in threaded view
|

## Re: 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 [hidden email] http://projects.scipy.org/mailman/listinfo/numpy-discussion
Open this post in threaded view
|

## Re: ANN: NumPy/SciPy Documentation Marathon 2008

 2008/5/20 Steven H. Rogers <[hidden email]>: >> .. [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 [hidden email] http://projects.scipy.org/mailman/listinfo/numpy-discussion
Open this post in threaded view
|

## Re: 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 [hidden email] http://projects.scipy.org/mailman/listinfo/numpy-discussion
Open this post in threaded view
|

## Re: 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/0e257bc8c116f73fI'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 <[hidden email]>: > 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 [hidden email] http://projects.scipy.org/mailman/listinfo/numpy-discussion mathml.patch (562 bytes) Download Attachment
Open this post in threaded view
|

## Re: 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 [hidden email] http://projects.scipy.org/mailman/listinfo/numpy-discussion
Open this post in threaded view
|

## Re: 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 <[hidden email]>: > > 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 [hidden email] http://projects.scipy.org/mailman/listinfo/numpy-discussion
Open this post in threaded view
|

## Re: ANN: NumPy/SciPy Documentation Marathon 2008

 In reply to this post by Joe Harrington 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 [hidden email] http://projects.scipy.org/mailman/listinfo/numpy-discussion
Open this post in threaded view
|

## Re: ANN: NumPy/SciPy Documentation Marathon 2008

 In reply to this post by Stéfan van der Walt 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/~robphone: 979-458-0096, fax: 979-845-6331 _______________________________________________ Numpy-discussion mailing list [hidden email] http://projects.scipy.org/mailman/listinfo/numpy-discussion
Open this post in threaded view
|

## Re: ANN: NumPy/SciPy Documentation Marathon 2008

 In reply to this post by Stéfan van der Walt 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/~robphone: 979-458-0096, fax: 979-845-6331 _______________________________________________ Numpy-discussion mailing list [hidden email] http://projects.scipy.org/mailman/listinfo/numpy-discussion
Open this post in threaded view
|

## Re: 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 [hidden email] http://projects.scipy.org/mailman/listinfo/numpy-discussion
Open this post in threaded view
|

## Re: ANN: NumPy/SciPy Documentation Marathon 2008

 In reply to this post by Jon Wright 2008/5/20 Jonathan Wright <[hidden email]>: > 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 [hidden email] http://projects.scipy.org/mailman/listinfo/numpy-discussion
Open this post in threaded view
|

## Re: 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_i18nIt 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 [hidden email] http://projects.scipy.org/mailman/listinfo/numpy-discussion