Re: [Discuss-gnuradio] Reference documentation to the python interface

[Ben Reynwar]

On Thu, Mar 8, 2012 at 8:35 AM, Tom Rondeau <address@hidden> wrote:
> On Thu, Mar 8, 2012 at 10:22 AM, Ben Reynwar <address@hidden> wrote:
>>
>> On Thu, Mar 8, 2012 at 7:19 AM, Michael Dickens <address@hidden> 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.
>
>
>
> 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
>

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