On Thu, Mar 8, 2012 at 11:44 AM, Ben Reynwar <b...@reynwar.net> wrote:
> On Thu, Mar 8, 2012 at 8:35 AM, Tom Rondeau <t...@trondeau.com> wrote: > > On Thu, Mar 8, 2012 at 10:22 AM, Ben Reynwar <b...@reynwar.net> wrote: > >> > >> On Thu, Mar 8, 2012 at 7:19 AM, Michael Dickens <m...@alum.mit.edu> > 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
_______________________________________________ Discuss-gnuradio mailing list Discuss-gnuradio@gnu.org https://lists.gnu.org/mailman/listinfo/discuss-gnuradio
