Enhancing Gnuradio Doxygen Generated Official Documentation

Dear Friends,

During the past period, I did a study on how to enhance our
automatically doxygen generated gnuradio documentation. I came up with
:

  1. The gnuradio code is mainly consists of C++ code ( *.cc, *.h) and
    python code ( *.py ) (this is already known fact).

  2. The C++ code classes and functions documentation are formated to
    confirm with doxygen special commands [ which starts with a backslash
    () or an at-sign (@)]. Thus, no problems in generating c++
    documentation using doxygen.

  3. The problem is in python code. The gnuradio python code documentation
    are formated to confirm with epydoc markup language and not doxygen.
    This formating looks ugly when interpreted by doxygen, so we cannot
    generate clear and nicely look python documentation using doxygen.

  4. These facts leads to :

a) We have to use doxygen for C++ documentation, and epydoc for python
code. This is not desirable, because we will end up with two separated
documents and moving from one to the other will make us sick!!.

b) Or, rewrite all python documentation to confirm with doxygen format.
In this case we will loose the functionality of doc and will may not
be able to use epydoc any more.

c) Or, to document everything twice (this will kill us).

d) Or (preferred), to use a filter program that will modify the python
code input to the doxygen in runtime. This will makes it possible to
use the Doxygen syntax inside python docstrings and automatically
generate API documentation out of it, instead of being forced to use the
non-native documentation blocks over the standard docstrings or to
document everything twice.

  1. Fortunately, doxygen has the ability (a really great feature) to
    automatically run a filter program during runtime on all its input files
    before parsing.

  2. Doing a Google search for such python filter program, I found two
    programs:

a) The first one was old and not updated (written in 2003 and it is not
working well with the currently updated doxygen versions).

b) The second one (doxypy.py) looks good. It is a python code written
under GPL V2.
The program description says : “The doxypy is an input filter for
Doxygen, it preprocesses python files so that docstrings of classes and
functions are reformatted into Doxygen-conform documentation blocks”

  1. The done work was :

a) Modifying the doxygen-in file (Doxyfile.in) to use the new filter.

b) Redefining the paths in this file to exclude unwanted swig
automatically generated python codes (which does not contain any
documentation).

c) Modifying the doxygen group definitions file (group_defs.dox) to
classify gnuradio blocks into a new group categories for ease of
exploring.

If Eric and Johnathan, approves the new documentation categories and/or
suggests a modifications, then I will slightly modify (and submit to
patch-gnuradio) most of gnuradio written source code files (about 80% -
90%) to be confirmed with the new suggested categories (putting the
@ingroup documentation line).

d) In this case (since I will edit all source files anyway ), I will try
also to add a new documentations to these files (I will need more time
to do it).

e) The new generated doxygen html files can be found in :

http://rapidshare.com/files/76826593/gnuradio-html-documentation.tar.gz

  1. To generate the new doxygen documentation files in your PC (if
    gnuradio is already installed):

a) Copy the attached files [doxypy.py , Doxyfile , group_defs.dox and
main_page.dox] into your xxxxx/gnuradio-core/doc folder.

b) Change directory to xxxxx/gnuradio-core/doc.

c) Run doxygen program without any arguments.

  1. For new gnuradio installation, the attached file [Doxyfile.in ]
    should be installed into your xxxxx/gnuradio-core/doc folder along
    with the [doxypy.py , group_defs.dox and main_page.dox] files .

Note:
I generated the [Doxyfile] file using doxygen version 1.5.3.

  1. Waiting for suggestions/modifications before I start modifying the
    gnuradio source files.

Regards,

Firas A.

Thanks for the tip! Works pretty well, except I don’t seem to get any
call
graphs.

A couple of tips:
FILTER_PATTERNS = *.py=doxypy.py

Also:
easy_install doxypy

Hi,

What do you mean by “call graphs” ?

Firas

Neal B. [email protected] wrote: Thanks for the tip! Works
pretty well, except I don’t seem to get any call
graphs.

A couple of tips:
FILTER_PATTERNS = *.py=doxypy.py

Also:
easy_install doxypy

Firas A. schrieb am 2007-12-16 09:18:

Hello Firas!

One small request: Please do not write HTML-Mail. Plain-Mail is much
easier to read (especially if you format your HTML to be very small) and
needs less space (Archive!).

Thank’s in advance!

Patrick

Engineers motto: cheap, good, fast: choose any two
Patrick S.
Student of Telematik, Techn. University Graz, Austria

This forum is not affiliated to the Ruby language, Ruby on Rails framework, nor any Ruby applications discussed here.

| Privacy Policy | Terms of Service | Remote Ruby Jobs