Re: [Discuss-gnuradio] Ben's docstring work

[Josh Blum]

On 10/14/2011 07:44 PM, Tom Rondeau wrote:
> 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.
> 

So suppose it this way:

Currently the docs/doxygen component builds a monolithic html and xml
folder for the whole project. I suppose we may like the monolithic html
because it makes a nice index.html and other index-like stuff. But the
purpose of the xml has been primarily to extract documentation
information (like in grc).

So, perhaps we keep the docs/doxygen html generator and turn off the
xml. In place of the monolithic xml, we have a per-component set of
build rules that calls doxygen on the headers to generate xml, and a
build rule that calls swig_doc.py to generate swig_doc.i. Think of a
macro that takes a list of .h files and generates the appropriate build
rules for xml, and then xml -> swig_docs.i.

If the docs are accessible through python, we probably dont need grc to
parse the xml. Instead, it can find the component in python and query
its docs, hopefully by reading the module's docstrings (__doc__) if it
really works like that.

-Josh