During the past period, I did a study on how to enhance our
automatically doxygen generated gnuradio documentation. I came up with
The gnuradio code is mainly consists of C++ code ( *.cc, *.h) and
python code ( *.py ) (this is already known fact).
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.
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.
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.
Fortunately, doxygen has the ability (a really great feature) to
automatically run a filter program during runtime on all its input files
Doing a Google search for such python filter program, I found two
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”
- 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
c) Modifying the doxygen group definitions file (group_defs.dox) to
classify gnuradio blocks into a new group categories for ease of
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 :
- 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.
- 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 .
I generated the [Doxyfile] file using doxygen version 1.5.3.
- Waiting for suggestions/modifications before I start modifying the
gnuradio source files.