[SciPy-dev] Accessible SciPy (ASP) project

[Travis Oliphant]

Arnd Baecker wrote:

>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!
>  
>
Thanks for the feedback.

>[...]
>
>  
>
>>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?
>  
>
This is the idea I have as well.

>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...))
>
>  
>
No, I know of no chm-producing tools on Linux.  For me that is a 
downside but not a show-stopper.  I need to look at documancer more.

>>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.
>  
>
Yes, the idea is that all of this extra stuff would be useful to the 
graphical help browser but wouldn't be in the doc-strings.   So, I think 
we are on the same page here.

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

I'd like to hear more input on the use of .chm files for the graphical 
help file.

-Travis