Re: [Discuss-gnuradio] Python level documentation

[Tom Rondeau]

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