On Wed, Nov 21, 2007 at 10:18:26AM -0800, Firas A. wrote:
Hi,
After about 20 days of hard working, I prepared an unofficial simple
gnuradio user manual. This draft manual should provide a printable gnuradio
documentation.
Although the doxygen is a great documentation technique to generate
documentation from the source code automatically, it depends on the
originally available documentation in the source code. If no remarks are
available, no documentation is generate ( you cannot get the water from a
dry sponge by squeezing it).
I hoped that this simple manual be published in gnuradio site, but I have
been told that "this approach is fundamentally broken and it is obsolete
the moment it is published, as the source code is constantly evolving", This
is absolutely true, but we had to do something.
I think, we can constantly follow gnuradio changes and modify the manual
accordingly. Thus, feedback is highly welcomed.
Here's my first set of suggestions:
* Submit patches to patch-gnuradio for missing or incorrect
documentation in the .h or .py files.
* Doxygen can generate XML output. That is, it'll handle the
automatic extraction for you. From there you could write some XSLT
that would convert that into docbook format. The docbook tools
provide several output formats including nice looking pdfs. This would
get us printed docs that track the source, and thus are "future
proof."
http://www.stack.nl/~dimitri/doxygen/output.html
The "Linux Documentation Project" uses docbook. Their docs provide
several recipes that may be useful. See for example,
http://tldp.org/LDP/LDP-Author-Guide/html/index.html
* Look at epydoc for extracting docs from the python code. Doxygen
also apparently has some support for this, but it's new and unfamiliar
to me. It's probably worth investigating.
FYI, docbook is nice in that it's non-proprietary, can be edited with
any text editor, and there is a complete set of free tools around it.
Thanks,
Eric