discuss-gnuradio
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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


From: Tom Rondeau
Subject: Re: [Discuss-gnuradio] Finished Unofficial Gnuradio User Manual
Date: Wed, 21 Nov 2007 15:05:44 -0500
User-agent: Thunderbird 2.0.0.9 (Windows/20071031)

Eric Blossom wrote:
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
Firas,

That's great what you've done, and I think Eric's suggestions are right on. As one of the guys to blame for lack of documentation in some of the blocks, I'm glad you've gone about solving some of this. It'd be great, though, if you could help us update the Doxygen comments in the code itself, which would help the project grow and keep the code relevant and understandable. Using Doxygen to produce documentation for the Python code, too, would be great.

Thanks again for your work,
Tom






reply via email to

[Prev in Thread] Current Thread [Next in Thread]