[SciPy-dev] Scipy help and documentation for end users
Fernando.Perez at colorado.edu
Fri Oct 1 11:22:25 CDT 2004
[ I'm relabeling this thread so it stands out, as I think this is a rather
important topic, hopefully the discussion can continue here and it will be
more obvious when browsing the archives.]
Robert Kern schrieb:
> Fernando Perez wrote:
>>I don't either, but I found this prechm.py, in python's CVS at Doc/tools:
>>I haven't tested it, but from the docstring, it will take html files and
>>wrap them into a .chm file. We could give it a try, and if it works
>>well enough, make a bundle of docs in this format.
> Not quite, AFAICT. It massages the existing HTML to what's necessary for
> Microsoft's help authoring tools to work. Their Windows-only software is
> still necessary to build the CHM file itself.
Bummer. I didn't have time to run a test last night.
This page has a useful discussion of documentation generation under Linux:
One option would be to use DocBook, which Lyx and OpenOffice both support.
But DocBook has a reputation for complexity, I don't really know how justified
or it truly is.
But back to the chm format as a possibility, perhaps not all is lost. While
there seems to be no native linux authoring tool, this thing:
is Windows freeware. I suspect, being a win95-compatible small program, it
will probably run just fine under Wine. So perhaps this could be used to make
the .chm files, which seems to be the sticking point. We've seen there are
good X window clients for this format, we just need to solve the authoring issue.
Anyway, whether it's docbook or chm, we certainly need a solid
documentation/help system integrated into this to make python/scipy more
approachable to new scientists. These are just some suggestions, and I'm sure
others know more about this than I do.
More information about the Scipy-dev