+++ /dev/null
-#
-# 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