Ben, Josh, Where are we with this? We had good momentum and were like 95% there, but then we dropped it about a month ago. I believe that Josh had a branch that, using cmake, took the docstrings code and would build a .i file per top-level component and install it with the Python code. I think the issue was that this only got the constructors, but Ben's note here talks about fixing that. Has this been ported to the cmake build process to autogenerate the doc strings?
Thanks, Tom On Tue, Oct 18, 2011 at 12:58 AM, Ben Reynwar <b...@reynwar.net> wrote: > I've made a few changes to doxyxml so that the DoxyFile objects should > be exposing their descriptions and have changed swig_doc.py so that > it's grabbing documentation from the file if it is present. It > doesn't appear to be picking any file descriptions up and I'm not sure > if that's because it's not working or because there aren't any. If > you know of some good blocks to test it on let me know. > commit is > https://github.com/benreynwar/gnuradio/commit/d6e36498174dcb20f92369cc6097514a5d102ded > > At the moment the layout for a docstring for a python creator function: > > """ > brief description from class > > detailed description from class > > brief description from make func > > detailed description from make func > > brief description from file > > detailed description from file > > Params: (list of input parameters) > """ > > The docstring for the class itself is the same without the parameter > list at the end. > > Cheers, > Ben > > On Mon, Oct 17, 2011 at 9:36 AM, Josh Blum <j...@joshknows.com> wrote: > > Ahhh much better. I added generation for a few of the components in core > > (general, gengen, filter, io) > > > http://gnuradio.org/cgit/jblum.git/commit/?h=swig_docs&id=d65572359a74e97ee6a01d89dcc44fd77ce54fef > > > > Basically, its pretty nice. The xml only regenerates when header files > > change, and the swig docs.i only regenerate when the xml is changed, and > > so on. No checked-in generated files. XML generation is very quick. Your > > python script actually takes a bit longer (but im not complaining). :-) > > > > I would like to get the grc docs parser looking for __doc__ strings soon. > > > > A few comments on your doc generator. Im not sure we agree on a standard > > here for documenting headers... but useful doc blocks may be in several > > places in the header: > > > > 1) docs for the factor/make function > > 2) docs for class definition > > 3) docs just in the header, think \file > > > > It looks like the generated docstrings only gets one of these. I suggest > > concatenating all forms of docs into the one class docstring so the full > > amount of docs is available at runtime to python. > > > > -Josh > > > >> > >> It was the position of the %include "swig_doc.i" in the digital_swig.i > file. > >> It needs to be at the top rather than at the bottom. > >> Here's a diff. > >> > >> diff --git a/gr-digital/swig/digital_swig.i > b/gr-digital/swig/digital_swig.i > >> index c804b5c..f6372b1 100644 > >> --- a/gr-digital/swig/digital_swig.i > >> +++ b/gr-digital/swig/digital_swig.i > >> @@ -23,6 +23,8 @@ > >> > >> %include <gri_control_loop.i> > >> > >> +%include "swig_doc.i" > >> + > >> %{ > >> #include "digital_binary_slicer_fb.h" > >> #include "digital_clock_recovery_mm_cc.h" > >> @@ -59,8 +61,6 @@ > >> %include "digital_cpmmod_bc.i" > >> %include "digital_gmskmod_bc.i" > >> > >> -%include "swig_doc.i" > >> - > >> #if SWIGGUILE > >> %scheme %{ > >> (load-extension-global "libguile-gnuradio-digital_swig" > >> "scm_init_gnuradio_digital_swig_module") > > > > _______________________________________________ > Discuss-gnuradio mailing list > Discuss-gnuradio@gnu.org > https://lists.gnu.org/mailman/listinfo/discuss-gnuradio >
_______________________________________________ Discuss-gnuradio mailing list Discuss-gnuradio@gnu.org https://lists.gnu.org/mailman/listinfo/discuss-gnuradio
