I've been doing a lot of work lately on the in-code documentation, and I've
finally gotten around to working with Ben Reynwar's docstring work to insert
the Doxygen docstrings into Python. This results in us being able call
help(gr.something) and get the full documentation that's available in the
header file. I've made a few changes, such as moving the meat of the code
into the docs directory and a few other minor things, and it's now in a
branch 'docstrings' available at:
git://github.com/trondeau/gnuradio.git
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 this
is not quite automatic, though it's _mostly_ automatic. The problem is that
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. This
means that you have to build once, run the swig_doc.py file to generate a
SWIG file from the XML files, then rebuild the entire project to insert the
documentation into Python.
The good news is that the .i file is kept in git and is part of the project,
so it's as relevant as the last time someone checked it in. So for the most
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 working
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 I
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.
1. Make sure the 'docs' component will be built, which requires
Doxygen.
2. Build the project like normal, which will run Doxygen and store the
XML files into $(top_builddir).
3. In $(top_srcdir)/docs/doxygen, run the command:
$ python swig_doc.py \
$(top_builddir)/docstrings/docs/doxygen/xml \
$(top_srcdir)/gnuradio-core/src/lib/swig/swig_doc.i
This uses the XML output of Doxygen to to rebuild a SWIG file that
contains all of the current Doxygen markups.
4. 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.
5. Install GNU Radio. Now, when you run help() in Python on a GNU
Radio block, you will get the full documentation.
===========================================================
Thanks,
Tom
_______________________________________________
Discuss-gnuradio mailing list
Discuss-gnuradio@gnu.org
https://lists.gnu.org/mailman/listinfo/discuss-gnuradio
