[SciPy-dev] Accessible SciPy (ASP) project
oliphant at ee.byu.edu
Tue Nov 2 11:31:21 CST 2004
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.
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
>((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
>> * 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
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.
I'd like to hear more input on the use of .chm files for the graphical
More information about the Scipy-dev