Python level documentation

GNU Radio
1

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

2

On Sun, Oct 10, 2010 at 7:40 PM, Ben R. [email protected] wrote:

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

3

On Fri, Oct 15, 2010 at 6:40 AM, Tom R. [email protected]
wrote:

creation and autogeneration, where you manually create the structure
documentation system on top of Doxygen wouldn’t be my first choice
effort of documentation like this would be worth the help it would be

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