[SciPy-dev] scipy/numpy documentation

[Gary Ruben]

Continuing the documentation topic, I just spent a few hours 
unsuccessfully trying to build the numarray documentation under Windows. 
It uses the Python standard documentation system which requires many 
dependencies under Windows (and I suspect under Linux) and the set-up is 
poorly documented.
The main Python documentation is based on a custom LaTeX 'manual.cls' 
class with specially defined macros. This is run through various tools 
to convert images, generate html versions, etc.
We have the choice of sticking with this system. I don't know what the 
implications of avoiding it by basing the spun-off version on a more 
standard LaTeX class are. For example, FiPy uses the memoir class, with 
which I am reasonably familiar. It is good for making books, but we 
wouldn't be able to take advantage of any tools which use the Python 
manual class with all the special Python LaTeX documentation markup. I'm 
guessing it's set up so that Windows compiled html (.chm) files can be 
easily generated in addition to the online html. This seems like a big 
advantage, so my tendency is to stick with this format. Other options, 
if we move away from the manual class, are the standard LaTeX book class 
or Koma-script.

Which way should we go with this?
If it's agreed to stick with the Python documentation system, I think 
I'll have to try again under Linux.

Gary R.