Re: [Discuss-gnuradio] Ben's docstring work

[Ben Reynwar]

On Sat, Oct 15, 2011 at 12:28 AM, Josh Blum <address@hidden> wrote:
>
>> Here's the information that I put into a README.doxyxml file for the
>> instructions to produce the docstrings:
>>
>> ===========================================================
>> The process of updating and exporting the Doxygen document strings
>> into Python consists of a few steps.
>>
>> 1. Make sure the 'docs' component will be built, which requires
>> Doxygen.
>>
>> 2. Build the project like normal, which will run Doxygen and store the
>>    XML files into $(top_builddir).
>>
>> 3. In $(top_srcdir)/docs/doxygen, run the command:
>>
>>    $ python swig_doc.py \
>>          $(top_builddir)/docstrings/docs/doxygen/xml \
>>          $(top_srcdir)/gnuradio-core/src/lib/swig/swig_doc.i
>>
>>    This uses the XML output of Doxygen to to rebuild a SWIG file that
>>    contains all of the current Doxygen markups.
>>
>> 4. Rebuild the GNU Radio libraries. Since gnuradio.i is included in
>>    all of the GNU Radio components, and gnuradio.i includes
>>    swig_doc.i, when the libraries are rebuilt, they will now include
>>    the documentation strings in Python.
>>
>> 5. Install GNU Radio. Now, when you run help() in Python on a GNU
>>    Radio block, you will get the full documentation.
>> ===========================================================
>>
>
>
> OK, so I ran swig_doc.py on gr-digital and got this swig_doc.i:
> http://pastebin.com/4HdhHC61 And the docstrings are clearly in there. I
> then added %include "swig_doc.i" to digital_swig.i. So now the module
> should be generated w/ the docstrings.
>
> So, how can I verify that this worked? I tried something like this:
> python -c "from gnuradio import digital; print
> help(digital.kurtotic_equalizer_cc)"
> Basically, where do the docstrings actually go in the module?
>
> Heres my work that does the build rules for swig docs in gr-digital:
> http://gnuradio.org/cgit/jblum.git/log/?h=swig_docs
>
> -Josh
>
>
>
> _______________________________________________
> Discuss-gnuradio mailing list
> address@hidden
> https://lists.gnu.org/mailman/listinfo/discuss-gnuradio
>

Hi Josh,

The docstrings should be accessible using the __doc__ property in the
normal way.

If you look at the generated python file the docstrings should be
present in the function and class definitions as usual.
e.g.
def kurtolic_equalizer_cc(blah blah):
    "docstring here"
    blah blah blah

If that's not happening, then it's not working.

I cloned your repo and checked out your swig_docs branch but got a
compilation error.

[ 46%] Generating gengen/gr_peak_detector_fb.i,
gengen/gr_peak_detector_ib.i, gengen/gr_peak_detector_sb.i
[ 51%] Built target gengen_generated
[ 51%] Swig source
[ 52%] Swig source
/home/ben/gnuradio-jblum/jblum/gnuradio-core/src/lib/gengen/gengen.i:33:
Error: Unable to find 'gengen_generated.i'
make[2]: *** [gnuradio-core/src/lib/swig/gnuradio_core_gengenPYTHON_wrap.cxx]
Error 1
make[1]: *** 
[gnuradio-core/src/lib/swig/CMakeFiles/_gnuradio_core_filter.dir/all]
Error 2
make: *** [all] Error 2

Cheers,
Ben