[SciPy-dev] Accessible SciPy (ASP) project

[Arnd Baecker]

On Mon, 1 Nov 2004, Travis Oliphant wrote:

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

Excellent!

[...]

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

What I had in mind with the graphical help-browser, was that
it can be used to display manuals, tutorials etc.
and doc-strings. Is there a way to supply the doc-strings
(maybe converted to html from ReST, including math)
to these chm browsers?

Do you know of any tools (under linux) to convert html documentation
to chm?
((BTW: that's what I like about documancer: it can deal
with html directly, so there is no need to have documentation
in different formats: for example on linux it is quite
common to have the html documenation for python installed locally,
so going for chm means that this contents has to be stored twice.
When saying this, I really think of the graphical help browser
to be _the_ way to access any type of documentation relevant
for scientific computing. This might mean for one person
to include documentation on PyTables, the other would
like to have OpenGL stuff and so on...))

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

I think this is a very good idea/approach. I have only
a problem with c): I often have to work
off-line (and many of our students as well), so I think
it is necessary to be able to access the additional information
also locally.
It might be problematic to add this to
the doc-strings themselves (because they could become too large,
including figures etc.), but maybe one could do the following:
 Create a directory .scipy in the home directory of the user
 into which all the additional documentation can be downloaded.
 When invoking the help command the usual information is displayed
 and then it is checked if further information
 is available and displayed.

This would have two benefits:
- the users can update the documentation on their own
  without fiddling around with the scipy installation
- a user could for himself add comments to routines
  easily (which he then submits to the Web-Page you suggested)

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

At the same time it would be good if this information
was available as a separate document (a kind of "topical guide") -
on the other hand your tutorial already addresses topics
of this type - so should one start from that and
convert it to pages on scipy.org?
((leaving aside, that the above chapters are not written
yet, if I remember correctly ;-))


To summarize:
 - I like the idea of documentation to which additions can be
   made a lot
 - it would be very important to me if that information is
   available locally as well
 - the idea of a graphical help browser needs further
   discussion IMHO
     - of course, content is king ;-), but it has to
       be accessible, so one should keep this point in mind
       when making any decision (on chm etc.)

Best,

Arnd