diff options
Diffstat (limited to 'gnuradio-core/doc/xml-swig/README')
| -rw-r--r-- | gnuradio-core/doc/xml-swig/README | 129 |
1 files changed, 129 insertions, 0 deletions
diff --git a/gnuradio-core/doc/xml-swig/README b/gnuradio-core/doc/xml-swig/README new file mode 100644 index 000000000..e5187df28 --- /dev/null +++ b/gnuradio-core/doc/xml-swig/README @@ -0,0 +1,129 @@ +# +# Copyright 2005 Free Software Foundation, Inc. +# +# This file is part of GNU Radio +# +# GNU Radio is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 3, or (at your option) +# any later version. +# +# GNU Radio is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with GNU Radio; see the file COPYING. If not, write to +# the Free Software Foundation, Inc., 51 Franklin Street, +# Boston, MA 02110-1301, USA. +# + +# +# Generating Python docstrings from C++ code using doxygen +# + +There are at least two strategies for this: + - use xsltproc as described below + - use doxy2swig.py (included in this directory) + +FIXME: get one of these working (probably doxy2swig since it doesn't +add any additional dependencies). + +---------------------------------------------------------------- + +Note: Robin's patch is in SWIG >= 1.3.23 + +-------------------------------------------------------------------------------- +From: http://mailman.cs.uchicago.edu/pipermail/swig/2004-October/010604.html + +> I applied the docstring patch. '%feature("autodoc",1");' is working as +> expected ... + +[problem solved. ...] + +> I can not agree more with the doxygen idea. I am using doxygen for +> documentation and I have been trying to put doxygen output to the +> python interface. Automatic generation of %feature("docstring") lines +> from doxygen output is the closest solution I can think of but the +> workload is still pretty big. How I wish this feature can be +> implemented in the near future. + +I have successfully extracted function/class description from doxygen +generated xml files, using an xslt script. To add doxygen generated +description to each class/function, you will need to (tested under +linux, note that this works only for Python, using Robin's docstring +patch) + +1. download swig source, apply Robin's docstring patch from + https://sourceforge.net/tracker/index.php?func=detail&aid=1023309&group_id=1645&atid=301645 + compile and install + +2. generate doxygen document with option "GENERATE_XML = YES" + +3. copy the attached script (save as swig.xsl) to the doc/xml directory + and run + + > xsltproc swig.xsl index.xml > temp_doc.i + > cat temp_doc.i | sed 's/"/\\"/g' | sed 's/__QuOtE__/"/g' > swig_doc.i + + you will get an interface file with lines like + %feature("docstring") class "class description"; + %feature("docstring") class::function "member function + description"; + + the second step is necessary since there might be " in descriptions + and I need to backquote them before I replace __QuOtE__ by real + quotes. (xslt experts may know how to post-process <xsl:value-of> and + make the script easier to use.) + +4. in your interface file, add + %include "siwg_doc.i" + %feature("autodoc","1") ; + +Hope this helps. + +swig.xsl: +========================================================= + +<!-- XSLT script to extract document for class/function for swig docstring + If you have xsltproc you could use: + xsltproc swig.xsl index.xml > swig_doc.i +--> +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> + <xsl:output method="text"/> + <xsl:template match="/"> + <!-- process each compound --> + <xsl:for-each select="doxygenindex/compound"> + <xsl:apply-templates select="document( concat( @refid, '.xml' ) )/*" /> + </xsl:for-each> + </xsl:template> + + <xsl:template match="doxygen"> + <xsl:for-each select="compounddef[@kind='class']"> + <xsl:text>%feature(__QuOtE__docstring__QuOtE__) </xsl:text> + <xsl:value-of select="compoundname"/> + <xsl:text> __QuOtE__ </xsl:text> + <xsl:value-of select="briefdescription"/><xsl:text> + </xsl:text> + <xsl:value-of select="detaileddescription"/> + <xsl:text> see also: </xsl:text> + <xsl:value-of select="includes"/> + <xsl:text>__QuOtE__; </xsl:text> + + <!-- output for each function individually --> + <xsl:for-each select="*/memberdef[@kind='function' and not(starts-with(name,'operator'))]"> + <xsl:text>%feature(__QuOtE__docstring__QuOtE__) </xsl:text><xsl:value-of select="../../compoundname"/>::<xsl:value-of select="name"/> + <xsl:text> __QuOtE__ </xsl:text> + <xsl:value-of select="definition"/> <xsl:value-of select="argsstring"/> + <xsl:text> + </xsl:text><xsl:value-of select="briefdescription"/><xsl:text> + </xsl:text><xsl:value-of select="detaileddescription"/> + <xsl:text>__QuOtE__; </xsl:text> + </xsl:for-each> + </xsl:for-each> + </xsl:template> +</xsl:stylesheet> + +-- +Bo Peng
\ No newline at end of file |