[Discuss-gnuradio] Enhancing Gnuradio Doxygen Generated Official Documentation

[Firas Abbas]

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.

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

6) 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"

7) 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


8) 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.

9) 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.

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


Regards,

Firas Abbas

doxy.rar
Description: pat176362781