Re: [Discuss-gnuradio] Finished Unofficial Gnuradio User Manual

[Eric Blossom]

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