I’ve been doing a lot of work lately on the in-code documentation, and
finally gotten around to working with Ben R.'s docstring work to
the Doxygen docstrings into Python. This results in us being able call
help(gr.something) and get the full documentation that’s available in
header file. I’ve made a few changes, such as moving the meat of the
into the docs directory and a few other minor things, and it’s now in a
branch ‘docstrings’ available at:
This branch has also been updated to the latest in next.
The issue that I wanted to bring up here is that the process for doing
is not quite automatic, though it’s mostly automatic. The problem is
the docs directory is processed last (and has to be), so the output XML
files that are parsed are not available until after the build is done.
means that you have to build once, run the swig_doc.py file to generate
SWIG file from the XML files, then rebuild the entire project to insert
documentation into Python.
The good news is that the .i file is kept in git and is part of the
so it’s as relevant as the last time someone checked it in. So for the
part, you don’t really have to worry about this process unless you are
changing documentation in the code. The bad part is that if you are
on the documentation, you have to remember to update this periodically.
I think that the benefits of this outweigh the negatives, and I’m about
ready to put this into our next branch so it will be a part of 3.5. But
wanted to give people some time to look over the process and suggest
possible modifications that might make things work more smoothly or even
integrated into the regular build process.
Here’s the information that I put into a README.doxyxml file for the
instructions to produce the docstrings:
The process of updating and exporting the Doxygen document strings
into Python consists of a few steps.
Make sure the ‘docs’ component will be built, which requires
Build the project like normal, which will run Doxygen and store the
XML files into $(top_builddir).
In $(top_srcdir)/docs/doxygen, run the command:
$ python swig_doc.py
This uses the XML output of Doxygen to to rebuild a SWIG file that
contains all of the current Doxygen markups.
Rebuild the GNU Radio libraries. Since gnuradio.i is included in
all of the GNU Radio components, and gnuradio.i includes
swig_doc.i, when the libraries are rebuilt, they will now include
the documentation strings in Python.
Install GNU Radio. Now, when you run help() in Python on a GNU
Radio block, you will get the full documentation.