[SciPy-dev] Accessible SciPy (ASP) project

[Arnd Baecker]

Hi,

there is one thing which is not quite clear to me yet
(sorry if I missed it):
There seem to be (at least?) three different types of documentation
  a) Manuals (like the Numeric manual)
  b) Tutorials (like Travis Oliphants scipy tutorial)
  c) doc-strings in the code

Personally I think that for a) and b) LaTeX is
a good choice.
However, for doc-strings in the code I think
that ReST is a good candidate.
(Also here I would like to see mathematical formulae,
which could be written in embedded LaTeX.)

Let me emphasize one point which is very important
according to our experience in teaching:
There should be one graphical interface
to access documents of all the above types.
This should include a good search capability and
the possibility of adding bookmarks (and more...).
It should also be easy to add further documents,
like the standard python documentation, wxPython docs,
Ipython manual, matplotlib tutorials/manuals, ...

A project which is pretty close to that is documancer,
   http://documancer.sourceforge.net/

(it will even work if you don't install wxMozilla, but
with a less capable html renderer).
I strongly recommend to try this out -
we have been using it successfully for a year now.

Documancer can (among others) handle html files
and can also use pydoc. For each "book" a search index
is generated once, which then allows very fast searching afterwards.
Also adding new documents is very simple.

One could pretty easily add a `ghelp search_topic` command (to IPython)
which opens documancer with the results of that search.
In addition for `ghelp command` one could convert the
corresponding doc-string to html (including any mathematical formulae)
and display it in documancer.

There would be a couple of further interesting
features one might like to have
(eg. cross-referencing within  a), b) and c) etc. ....)

Another point would be that the
user can add own comments, examples etc. at any place
(locally stored).
If then there is a well-defined path how to transfer
these additions to the doc-strings and manuals
this might also enhance the possibility of user contributions.

I am certain, there are many pros and cons and technical problems
concerning the above ideas, but maybe parts of
this could become reality?

Just my 2 cents, best,

Arnd