Automatic documentation of rsf Python package

[sfomel]

I got a first version of the automatic documentation for the rsf Python package going. You can see it at http://m8r.info/rsf_epydoc/ . Creating it was as simple as typing:

epydoc --html rsf -o rsf_epydoc --exclude rsf.sf* --exclude rsf.use --exclude rsf.vpplot

at a command line of a machine with Epydoc installed (in my case, a Fedora 14 machine).

Other tools (Doxygen, pydoctor, etc) can be used in a similarly easy manner, it is a matter of reading the documentation and experimenting. The look-and-feel of the output can be adjusted for all these tools via stylesheets, logos can be used, etc. A lot of room to play. Most of these tools create also pdf, ps, latex output... you name it.

The process of creating the documentation for the rsf package still has to be integrated with the build process. Ideally config would detect which of the py self-doc tools, if any, are installed on the system, and use whatever is available, in the preference order specified by default or overridden by the user's call to config.

A small difficulty that needs to be solved first, regardless of what autodoc generator is used, is that the package needs to exist before the documentation is run. So this means that the Python package should be created during the build phase in RSFSRC/build/lib/python... (cue in the fun with the Mac locations), then self-doc run on it, then install puts everything in the final location. Right now install builds the Python package on the fly... The call to Epydoc will also change in that case -- instead of specifying a package name ("rsf"), filenames will be specified.

Reported by: ivlad

[sfomel]

• status: open --> pending
• assigned_to: Nick Vlad
• Group: --> NextRelease(example)

Original comment by: sfomel