Re: [Discuss-gnuradio] Python level documentation

[Ben Reynwar]

On Fri, Oct 15, 2010 at 6:40 AM, Tom Rondeau <address@hidden> wrote:
> On Sun, Oct 10, 2010 at 7:40 PM, Ben Reynwar <address@hidden> 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