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

[Ben Reynwar]

On Thu, Mar 8, 2012 at 10:01 AM, Tom Rondeau <address@hidden> wrote:
> On Thu, Mar 8, 2012 at 11:44 AM, Ben Reynwar <address@hidden> wrote:
>>
>> 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
>
>
> 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
>
>
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.