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
>