On Fri, Oct 15, 2010 at 6:40 AM, Tom Rondeau <trondeau1...@gmail.com> wrote: > On Sun, Oct 10, 2010 at 7:40 PM, Ben Reynwar <b...@reynwar.net> wrote: >> 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. > > Thanks for taking a stab at this, Ben! > > I'm not convinced right now that this is the best way to handle it. > What's wrong with using Doxygen for the Python documentation as well? > I've never tried to do this myself, but I think other people have. No > one's really seemed to "get it right." But adding another > documentation system on top of Doxygen wouldn't be my first choice > (we're already heavy on dependencies, and I try to avoid adding more > if it can be helped). Also, I'm not fond of having a file that has to > be maintained like this. > > Now, if you can show that this is really the best way to go, I'll reconsider. > >> 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 > > So right now, this seems most helpful in exposing the namespace and > the Python modules. Everything inside is just a link to the C++ > documentation. I'm not sure that's quite enough to make this kind of > documentation worthwhile. > > Now, I think the real benefit for doing Python-level code > documentation is in the all-Python blocks. Specifically, there's a lot > of under-documented and under-exposed stuff sitting in the blks2 > module (gnuradio-core/src/python/gnuradio/blks2impl). Also, there are > all of the examples. If you can get a good documentation system for > them so that we can easily browse it and generate it, then I think > that's greatly beneficial to the community. > > I'm not trying to be discouraging here. Hopefully, you can see where > I'm coming from. > > Thanks, > Tom >
I agree that pure autogeneration would be nicer. However I would use epydoc rather than doxygen simply because doxygen isn't often used for python code and trying to use it would be making things unnecessarily difficult. I don't think an added dependency is too much of an issue because few users will generate their own documentation when they can easily access it online. I generated epydoc docs while I was experimenting with autogeneration. They're at www.reynwar.net/gnuradio/epydoc/. The main problem (besides the lack of docstrings) is that the python namespaces are a mess, so the generated docs are too. The __module__ attribute of objects is often not set to the correct module. For example gnuradio.gr.head.__module__ is gnuradio.gr.gnuradio_swig_py_general and gnuradio.blks2.analysis_filterbank.__module__ is gnuradio.blks2impl.filterbank. If the __module__ attributes were set correctly and only the necessary items were exported then the autogenerated documentation would be much more useable. Is that a documentation direction that you are more comfortable with? I'm happy to start doing some tidying up if it is. Cheers, Ben _______________________________________________ Discuss-gnuradio mailing list Discuss-gnuradio@gnu.org http://lists.gnu.org/mailman/listinfo/discuss-gnuradio
