# # 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