Hi all,
I have a patch to generate docstrings from the doxygen-generated xml files.
It follows the suggestions in gnuradio/docs/doxygen/xml-swig/README.
swig.xsl is based on gnuradio/docs/doxygen/xml-swig/swig.xsl
The funkiness that is gr_swig_block_magic.i meant that I had to modify
the method a little but it's basically the same.
I haven't attempted to incorporate the docstring generation into a
make file, because it wasn't obvious to me how to do so, and I thought
someone who's already played around with those would be able to do it
with much less chance of messing everything up. Anytime a header file
is modified it would require regeneration of the doxygen documentation
and the swig_doc.i file before SWIG is run again.
It currently only works for blocks beginning with "gr_", although not
for any particularly good reason. I've only tested in on docstring
generation for blocks and their methods so it almost certainly won't
generate all the docstrings one would like.
I plan to continue working on this but thought I would submit this
patch, since it does add most docstrings and doesn't appear to break
anything.
Cheers,
Ben
From 737ef355e80f46b180665d19ddc3bb5f16419567 Mon Sep 17 00:00:00 2001
From: Ben Reynwar <b...@reynwar.net>
Date: Mon, 13 Sep 2010 14:43:58 -0700
Subject: [PATCH] Script to convert doxygen-generated xml files into python docstrings.
Not yet included in make files.
---
gnuradio-core/src/lib/swig/gr_swig_block_magic.i | 2 +
gnuradio-core/src/lib/swig/make_swig_doc.sh | 13 +++
gnuradio-core/src/lib/swig/swig.xsl | 115 ++++++++++++++++++++++
3 files changed, 130 insertions(+), 0 deletions(-)
create mode 100755 gnuradio-core/src/lib/swig/make_swig_doc.sh
create mode 100644 gnuradio-core/src/lib/swig/swig.xsl
create mode 100644 gnuradio-core/src/lib/swig/swig_doc.i
diff --git a/gnuradio-core/src/lib/swig/gr_swig_block_magic.i b/gnuradio-core/src/lib/swig/gr_swig_block_magic.i
index 78e8380..90b4983 100644
--- a/gnuradio-core/src/lib/swig/gr_swig_block_magic.i
+++ b/gnuradio-core/src/lib/swig/gr_swig_block_magic.i
@@ -20,6 +20,8 @@
* Boston, MA 02110-1301, USA.
*/
+%include <swig_doc.i>
+
%define GR_SWIG_BLOCK_MAGIC(PKG, BASE_NAME)
_GR_SWIG_BLOCK_MAGIC_HELPER(PKG, PKG ## _ ## BASE_NAME, BASE_NAME)
%enddef
diff --git a/gnuradio-core/src/lib/swig/make_swig_doc.sh b/gnuradio-core/src/lib/swig/make_swig_doc.sh
new file mode 100755
index 0000000..454a9ed
--- /dev/null
+++ b/gnuradio-core/src/lib/swig/make_swig_doc.sh
@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+
+# Uses the doxygen-generated xml files to generate swig_doc.i.
+# swig_doc.i contains docstrings to be used by SWIG.
+
+basedir="../../../.."
+swigdir="$basedir/gnuradio-core/src/lib/swig"
+doxydir="$basedir/docs/doxygen"
+
+cp $swigdir/swig.xsl $doxydir/xml/swig.xsl
+xsltproc $doxydir/xml/swig.xsl $doxydir/xml/index.xml > $swigdir/temp_doc.i
+cat $swigdir/temp_doc.i | sed 's/"/\\"/g' | sed 's/__Qu0tE__/"/g' > $swigdir/swig_doc.i
+rm $swigdir/temp_doc.i
diff --git a/gnuradio-core/src/lib/swig/swig.xsl b/gnuradio-core/src/lib/swig/swig.xsl
new file mode 100644
index 0000000..d398f62
--- /dev/null
+++ b/gnuradio-core/src/lib/swig/swig.xsl
@@ -0,0 +1,115 @@
+<!-- XSLT script to convert doxygen generated xml files into an interface file
+ that can be used by SWIG.
+
+ The comment corresponding to a block gr_does_stuff would result in:
+
+ %feature("docstring") gr_make_does_stuff "comment";
+ %feature("docstring") boost::shared_ptr<gr_does_stuff> "comment";
+
+ These two lines are required because gr.does_stuff in python is not a class,
+ rather it corresponds to gr_make_does_stuff. However we want the comment
+ associated with the gr_does_stuff in the C code to produce docstrings in
+ both the generating function gr.does_stuff and the generated class instances
+ gr.does_stuff(). These two lines should do this.
+
+ Comments for class methods are more simple.
+
+ %feature("docstring") gr_does_stuff::do_stuff "I do stuff";
+
+ (Assumes that blocks begin with gr_.)
+ -->
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"; version="1.0">
+ <xsl:output method="text"/>
+ <xsl:template match="/">
+ <!-- process each compound one by one -->
+ <xsl:for-each select="doxygenindex/compound">
+ <xsl:apply-templates select="document( concat( @refid, '.xml' ) )/*" />
+ </xsl:for-each>
+ </xsl:template>
+
+ <xsl:variable name="quote" select="'__Qu0tE__'"/>
+
+ <xsl:template match="doxygen">
+ <xsl:for-each select="(compounddef[(@kind='class' or @kind='namespace')])">
+ <!-- FIXME: Can't yet handle template compound names.
+ Swig dies at double template e.g.
+ %feature("docstring") boost::shared_ptr<gr_single_pole_iir< gr_complex, i_type, double >> "comment"
+ We get round this just be avoiding compound names containing '<'.
+
+ FIXME: Only works for blocks starting with gr_
+ -->
+ <xsl:choose><xsl:when test="starts-with(compoundname, 'gr_') and not(contains(compoundname, '<'))">
+
+ <!-- e.g. %feature("docstring") gr_make_does_stuff "comment"; -->
+ <xsl:value-of select="concat('%feature(',$quote,'docstring',$quote,') ')"/>
+ <xsl:apply-templates select="compoundname" mode="add_make"/>
+ <xsl:text> </xsl:text>
+ <xsl:value-of select="$quote"/>
+ <xsl:apply-templates select="briefdescription"/>
+ <xsl:text>

</xsl:text>
+ <xsl:apply-templates select="detaileddescription"/>
+ <xsl:text>

</xsl:text>
+ <xsl:text>see also:</xsl:text>
+ <xsl:value-of select="includes"/>
+ <xsl:value-of select="$quote"/>
+ <xsl:text>;
</xsl:text>
+
+ <!-- e.g. %feature("docstring") boost::shared_ptr<gr_does_stuff> "comment"; -->
+ <xsl:value-of select="concat('%feature(',$quote,'docstring',$quote,') ')"/>
+ <xsl:apply-templates select="compoundname" mode="shared_ptr"/>
+ <xsl:text> </xsl:text>
+ <xsl:value-of select="$quote"/>
+ <xsl:apply-templates select="briefdescription"/>
+ <xsl:text>

</xsl:text>
+ <xsl:apply-templates select="detaileddescription"/>
+ <xsl:text>

</xsl:text>
+ <xsl:text>see also:</xsl:text>
+ <xsl:value-of select="includes"/>
+ <xsl:value-of select="$quote"/>
+ <xsl:text>;
</xsl:text>
+
+ <!-- output for each function individually -->
+
+ <xsl:for-each select="*/memberd...@kind='function' and not(starts-with(name,'operator')) and not (starts-with(name, '~'))]">
+ <xsl:value-of select="concat('%feature(',$quote,'docstring',$quote,') ')"/>
+ <xsl:value-of select="../../compoundname"/>::<xsl:value-of select="name"/>
+ <xsl:text> </xsl:text>
+ <xsl:value-of select="$quote"/>
+ <xsl:value-of select="definition"/>
+ <xsl:apply-templates select="argsstring"/>
+ <xsl:text>
</xsl:text>
+ <xsl:apply-templates select="briefdescription"/>
+ <xsl:text>

</xsl:text>
+ <xsl:apply-templates select="detaileddescription"/>
+ <xsl:value-of select="$quote"/>
+ <xsl:text>;
</xsl:text>
+ </xsl:for-each>
+
+ </xsl:when></xsl:choose>
+ </xsl:for-each> </xsl:template>
+
+ <!-- e.g. Change gr_channel_model to gr_make_channel_model -->
+ <xsl:template match="compoundname" mode="add_make">
+ <xsl:call-template name="AddMake">
+ <xsl:with-param name="body" select="."/>
+ </xsl:call-template>
+ </xsl:template>
+
+ <xsl:template name="AddMake">
+ <xsl:param name="body"/>
+ <xsl:value-of select="concat(substring-before($body, '_'), '_make_', substring-after($body, '_'))"/>
+ </xsl:template>
+
+ <!-- e.g. Change gr_channel_model to boost::shared_ptr<gr_channel_model> -->
+ <xsl:template match="compoundname" mode="shared_ptr">
+ <xsl:call-template name="SharedPtr">
+ <xsl:with-param name="body" select="."/>
+ </xsl:call-template>
+ </xsl:template>
+
+ <xsl:template name="SharedPtr">
+ <xsl:param name="body"/>
+ <xsl:value-of select="concat('boost::shared_ptr<',$body,'>')"/>
+ </xsl:template>
+
+</xsl:stylesheet>
diff --git a/gnuradio-core/src/lib/swig/swig_doc.i b/gnuradio-core/src/lib/swig/swig_doc.i
new file mode 100644
index 0000000..e69de29
--
1.7.0.4
_______________________________________________
Patch-gnuradio mailing list
Patch-gnuradio@gnu.org
http://lists.gnu.org/mailman/listinfo/patch-gnuradio
