I’ve got a somewhat complete reference for the python interface of
gnuradio radio done now. It can be found at:
www.reynwar.net/gnuradio/sphinx/
Any suggestions on how we could improve these docs?
I also have two questions:
- I need improved docstrings for the subpackages. In particular
noaa, pager, and video_sdl. Suggestions from people who know what
these are would be much appreciated.
- A lot of python blocks contain doxygen markup (e.g. @param).
Anyone object to me changing this to a more pythonesque format since
we’re not using doxygen for the python code? For example:
“”"
brief description
detailed description
Args:
arg1: description
arg2: description
“”"
can be easily parsed by sphinx.
I’ve also modifed doxyxml so that it extracts parameter
descriptions from the doxygen xml, and swig_doc.py so that it
generates docstrings for the swiged blocks in the above format.
Things to do:
- Add a sphinx extension to automate the inclusion of signal processing
blocks.
- Handling of latex formatted math notation.
Cheers,
Ben
On Wed, Mar 07, 2012 at 04:36:57PM -0700, Ben R. wrote:
I’ve got a somewhat complete reference for the python interface of
gnuradio radio done now. It can be found at:
www.reynwar.net/gnuradio/sphinx/
Hi Ben,
fantastic stuff!
Any suggestions on how we could improve these docs?
I’m not sure if this goes here or if it’s due to the swig_doc stuff, but
it would be great if block methods would also appear in the docs. A lot
of the blocks have functions to configure them (e.g. add_cc.set_k())
which aren’t in the docs.
But it’s still great stuff 
MB
–
Karlsruhe Institute of Technology (KIT)
Communications Engineering Lab (CEL)
Dipl.-Ing. Martin B.
Research Associate
Kaiserstraße 12
Building 05.01
76131 Karlsruhe
Phone: +49 721 608-43790
Fax: +49 721 608-46071
www.cel.kit.edu
KIT – University of the State of Baden-Württemberg and
National Laboratory of the Helmholtz Association
Hi Ben - Ditto Martin: great stuff! I think “keep filling in the
blanks” is my improvement recommendation 
– some items contain “This
docstring is not useful” or the equivalent, or are just empty (e.g.,
“gnuradio.optfir.band_pass”). I’m guessing some items are like this
because the source code does not contain useful info (yet). Nice work!
On Thu, Mar 8, 2012 at 7:00 AM, Martin B. [email protected]
wrote:
Any suggestions on how we could improve these docs?
I’m not sure if this goes here or if it’s due to the swig_doc stuff, but
it would be great if block methods would also appear in the docs. A lot
of the blocks have functions to configure them (e.g. add_cc.set_k())
which aren’t in the docs.
Yep, I overlooked this. Thanks for pointing it out.
On Thu, Mar 8, 2012 at 10:22 AM, Ben R. [email protected] wrote:
an undertaking that I am not keen or able to do. In optfir.bandpass
it is because the documentation is given as a comment rather than a
docstHopefully having the documentation accessible like this will help
us spot where documentation needs work.
Hey Ben,
Since you’re having more luck with Sphinx than we have in the past with
Doxygen for the Python documentation, I’d say we’re ok changing the
documentation markup to make it more friendly with Sphinx. I think
you’re
right that a lot of the empty documentation here is due to the
formatting
of the documentation in the Python files (as well as an absence in some
instances).
Have you been able to fully automate the process? I think that’s really
key
to the success. We don’t want any manual effort to have to go into
building
these.
When you’ve got it working and everything, we can then update the
documentation on the Wiki for how to document the Python code so that it
works nicely with this.
Thanks!
Tom
On Thu, Mar 8, 2012 at 7:19 AM, Michael D. [email protected]
wrote:
Hi Ben - Ditto Martin: great stuff! I think “keep filling in the blanks” is my
improvement recommendation – some items contain “This docstring is not useful”
or the equivalent, or are just empty (e.g., “gnuradio.optfir.band_pass”). I’m
guessing some items are like this because the source code does not contain useful
info (yet). Nice work! - MLD
Yeah, I think in most cases it’s because the documentation is missing
in the source code, and fixing that for all of gnuradio is obviously
an undertaking that I am not keen or able to do. In optfir.bandpass
it is because the documentation is given as a comment rather than a
docstHopefully having the documentation accessible like this will help
us spot where documentation needs work.
On Thu, Mar 8, 2012 at 11:44 AM, Ben R. [email protected] wrote:
because
key
gnuradio.digital.my_new_function
to gnuradio/docs/sphinx/digital/index.rst
and the line
… autofunction:: gnuradio.digital.my_new_function
to gnuradio/docs/sphinx/digital/utilities.rst
Tha’s ok. When I was talking about being automated, I was really
thinking
about automating the generation of the output docs during make. I think
you
had said before that there was some hand-editing you were doing each
time.
As long as we just have to amend the index file once for a new block,
that’s fine. I just don’t want to have to do any manual intervention
every
time we want to build it.
Tom
On Thu, Mar 8, 2012 at 10:01 AM, Tom R. [email protected] wrote:
docstring is not useful" or the equivalent, or are just empty (e.g.,
instances).
desirable that all functions defined appear in the documentation,
to gnuradio/docs/sphinx/digital/utilities.rst
Ah! No wonder you were worried :). Sorry for the confusion. I meant
that I couldn’t completely automate the generation of the files which
are then used to generate the documentation.
On Thu, Mar 8, 2012 at 8:35 AM, Tom R. [email protected] wrote:
in the source code, and fixing that for all of gnuradio is obviously
documentation markup to make it more friendly with Sphinx. I think you’re
works nicely with this.
Thanks!
Tom
I haven’t done any work on the automation yet. My goal with that is
to automate the inclusion of signal processing blocks but to leave
other objects to be added manually. So if you add a new signal
processing block the documentation should take care of itself, but if
you add a new utility function you have to explicitly alter the
documentation source files so that it is included. Since it’s not
desirable that all functions defined appear in the documentation,
something like this is necessary. For example, if you added a new
utility function to gr.digital this might consist of adding the line
gnuradio.digital.my_new_function
to gnuradio/docs/sphinx/digital/index.rst
and the line
… autofunction:: gnuradio.digital.my_new_function
to gnuradio/docs/sphinx/digital/utilities.rst