[SciPy-dev] Accessible SciPy (ASP) project

[Travis Oliphant]

I should chime in here on SciPy documentation, as I am trying to set-up 
a system that would allow users to contribute documentation to Python in 
a more fluid manner.

First of all,  tools such as LyX and TeXMacs make the LaTeX-is-too-hard 
line out of date.    LyX for example is not hard to use to write 
documentation.  Native binaries are available on Windows.    People who 
still flounder in raw LaTeX have just not made use of the more useful 
front ends.

With that said,  I agree with Eric that we should worry less about a 
standard and more about the actual documentation.     I also agree that 
there are multiple documents to be produced and these may use multiple 
formats.

For me the most important issues are: 

1)  agreeing on a common command to bring up a graphical help browser 
(what that browser is could change over time---and even be set by the 
user).   I like ghelp as the command to use, and feel that bringing up a 
chm browser is a good start. 

2)  improving the docstring documentation.  

Here is a plan for doing number 2.

1) First, use ReST in docstrings along with latex math commands where 
needed.  i.e. $\alpha = \int_0^b f(x) \, dx$ 

2) Set up a site (e.g. www.scipy.org/livedocs) which has all the 
docstrings from scipy available in a hierarchial form.
    * On each page there is documentation for a single function or class. 
    * The documentation is separated into three parts:
          a)  the one-liner
          b)  the docstring to be included in the scipy code
          c)  extra examples, documentation that will not be included in 
the code, but stay on the website.
     * Every docstring in scipy contains a link back to the appropriate 
livedoc page so that users can edit it and/or find out more about the 
function.

     * Ultimately the website could convert latex code to images and 
create a nice looking document.

Gettting this working perfectly requires a bit of effort.  But a simple 
implementation is not that hard.

Comments are welcome.

Another documentation effort should start creating scipy.org pages that 
just give examples for doing common things:

* Least-square fitting
* Solving systms of equations.
* Optimization
* Reading and writing files

Perhaps here could go the slides for some of the tutorials that have 
been given on SciPy. 

-Travis O.