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.
For those interested in helping me to correct the manual or adding more
details, I can receive their remarks/modifications on my email, and I
will
reflect the suggestions/changes immediately to the original source.
On Wed, Nov 21, 2007 at 10:18:26AM -0800, Firas A. wrote:
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.”
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.
originally available documentation in the source code. If no remarks are
automatic extraction for you. From there you could write some XSLT
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.
Submit patches to patch-gnuradio for missing or incorrect
documentation in the .h or .py files.
Ok. I will start doing it.
The “Linux Documentation Project” uses docbook. Their docs provide
Thanks,
Eric
It seems that doxygen has many interesting back doors!!.Look to the
following documentation generated by doxygen : http://kdevelop.org/HEAD/doc/api/html/
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
Dear Eric, Tom
I will try to follow your advices, and will try to master doxygen and
find
out how to use it to produce nice and useful gnuradio documentation.
Thank
you.
On Wed, Nov 21, 2007 at 01:14:59PM -0800, Firas A. wrote:
Dear Eric, Tom
I will try to follow your advices, and will try to master doxygen and find
out how to use it to produce nice and useful gnuradio documentation. Thank
you.
Firas
Thanks! Looking forward to seeing what you come up with.
Thanks for creating the manual. As a new user, it has already helped me
find various bits and pieces that I may never have found otherwise.
Whilst the manual as-is makes a great reference document, can I suggest
that for a new user at least, it would be even more helpful if the
information was ordered differently - perhaps along the following lines.
Sources
noise_source_x
sig_source_x
vector_source_x
file_source
…
Sinks
fft_sink_x
…
Filters
Hardware control
Encoders (cross-referenced to the relevant decoder)
Decoders (cross-referenced to the relevant encoder)
Mathematical operators
…
Further, it would be helpful if the document identified those things
that were deprecated and due to disappear in a future release (e.g.
fftsink2.fft_sink_x should be used in preference to fftsink.fft_sink_x,
I believe).
Also, the “examples” section for each block is a great idea - but
doesn’t seem to be complete. For example, audio.sink is used in
gnuradio-examples/python/audio/audio_play.py, but that isn’t referenced
in 1.25.2.
A minor point - I note that 1.8.16.4 says file_decriptor_[sink|source].
Presumably this is a typo and should be file_descriptor_[sink|source]
(decr -> descr)
We need a tracking mechanism and way to submit corrections, additions,
upgrades as a community and to track “who did what to whom”. You have
done a fantastic job of starting this but we need to already plan while
the “Arnold Dumey microsecond” has not passed for AF (After Firas) and
wouldn’t it be better to do it WF (with Firas). Having done this kind
of thing on other projects, I started off well and when I began to tire
of the drudgery and repetitive parts of this, the effort inevitably
faltered. I feel this is too important to fail to prevent the
consequences of the inevitable “moving on” to other newer and more
interesting things than doing a manual. It is clear that you are smart,
intelligent, well informed, and capable of moving on. To me that makes
in inevitable. Why aren’t we doing this (officially) as part of our
wiki? Are the wiki controls/tools too lightweight for this level of
effort? If the answer is “no they are adequate” or “they can easily be
made adequate”, then the gnuradio wiki is the obvious (and IMHO) correct
place for this.
Again, please accept my sincerest gratitude for doing what should have
been done ages ago and wasn’t.
Bob
Firas A. wrote:
Sources
Regards,
Firas,
–
AMSAT Director and VP Engineering. Member: ARRL, AMSAT-DL,
TAPR, Packrats, NJQRP, QRP ARCI, QCWA, FRC. ARRL SDR WG Chair
“An optimist may see a light where there is none, but why
must the pessimist always run to blow it out?†Descartes
You are welcomed. The published document is just a simple start, and I’m
planing to do :
Publish updated version document with more documentations and more
error correction in the next one or two days at most.
To add/create (in the near future) a new block ordering such as :
Sources
Sinks
Signal processing
Type conversion
Digital Filtering
Signal Modulation
Signal Demodulation
Tools
USRP
-… any more suggestions are highly welcomed
Add a blocks alphabetical index (in near future).
To Apply all these documentations in the original gnuradio source
files and send it as patches to gnuradio developers (administrators) ,
so that the official gnuradio documentation generated by doxygen will
give us more information.
Trying to find/build a new doxygen configuration to file to make it
generate a more clearing picture and send this a patch to gnuradio.
Thanks for creating the manual. As a new user, it has already helped me
find various bits and pieces that I may never have found otherwise.
Whilst the manual as-is makes a great reference document, can I suggest
that for a new user at least, it would be even more helpful if the
information was ordered differently - perhaps along the following lines.
Sources
noise_source_x
sig_source_x
vector_source_x
file_source
…
Sinks
fft_sink_x
…
Filters
Hardware control
Encoders (cross-referenced to the relevant decoder)
Decoders (cross-referenced to the relevant encoder)
Mathematical operators
…
Further, it would be helpful if the document identified those things
that were deprecated and due to disappear in a future release (e.g.
fftsink2.fft_sink_x should be used in preference to fftsink.fft_sink_x,
I believe).
Also, the “examples” section for each block is a great idea - but
doesn’t seem to be complete. For example, audio.sink is used in
gnuradio-examples/python/audio/audio_play.py, but that isn’t referenced
in 1.25.2.
A minor point - I note that 1.8.16.4 says file_decriptor_[sink|source].
Presumably this is a typo and should be file_descriptor_[sink|source]
(decr -> descr)
We need a tracking mechanism and way to submit corrections, additions,
upgrades as a community and to track “who did what to whom”.
After I finish what I’m planing to do, I will try to look/investigate
for such tracking mechanism and if necessary, build a new documentation
tool (like the doxygen) especially dedicated for gnuradio. In the mean
time, we had to finish something in order to move away from square one
and step into square two.
wiki? Are the wiki controls/tools too lightweight for this level of
effort? If the answer is “no they are adequate” or “they can easily be
made adequate”, then the gnuradio wiki is the obvious (and IMHO) correct
place for this.
To make people appreciate/participate in your work, they have to
understand what your doing. Since the gnuradio is something fantastic,
this means, that we have no option to be tired of doing the drudgery and
repetitive parts of the documentation.
Again, please accept my sincerest gratitude for doing what should have
been done ages ago and wasn’t.
Bob
Thank you, for you too Bob.
Regards,
Firas
This forum is not affiliated to the Ruby language, Ruby on Rails framework, nor any Ruby applications discussed here.