[Discuss-gnuradio] Python level documentation

[Ben Reynwar]

Hi all,

I've been experimenting with creating some python level documentation
for gnuradio to complement the existing doxygen docs.

My first attempt was pure autogeneration, but I wasn't successful in
creating any documentation that wouldn't be more painful to wade
through than the source code itself.  I'm currently of the opinion
that using Sphinx is the way to go.  It's a compromise between manual
creation and autogeneration, where you manually create the structure
of the documentation but the docstrings are automatically pulled out
of the python modules.  It also easy using Sphinx to create links from
the python docs to the doxygen C++ docs.

I've created some example documentation and put it online at
www.reynwar.net/gnuradio/sphinx/.  It's only a small subsection of
gnuradio, because I didn't want to go to the effort of creating it all
until I got some feedback.  Do you guys think that the maintenance
effort of documentation like this would be worth the help it would be
to beginning users?  If you click on the 'Show Source' link on the nav
bar you can see text files that would need to be manually maintained.

Cheers,
Ben