[Discuss-gnuradio] Ben's docstring work

[Tom Rondeau]

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