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 _______________________________________________ Discuss-gnuradio mailing list Discuss-gnuradio@gnu.org https://lists.gnu.org/mailman/listinfo/discuss-gnuradio
