On Thu, Mar 8, 2012 at 10:01 AM, Tom Rondeau <t...@trondeau.com> wrote: > 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 > > 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.
_______________________________________________ Discuss-gnuradio mailing list Discuss-gnuradio@gnu.org https://lists.gnu.org/mailman/listinfo/discuss-gnuradio
