2 # Copyright 2005 Free Software Foundation, Inc.
4 # This file is part of GNU Radio
6 # GNU Radio is free software; you can redistribute it and/or modify
7 # it under the terms of the GNU General Public License as published by
8 # the Free Software Foundation; either version 2, or (at your option)
11 # GNU Radio is distributed in the hope that it will be useful,
12 # but WITHOUT ANY WARRANTY; without even the implied warranty of
13 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 # GNU General Public License for more details.
16 # You should have received a copy of the GNU General Public License
17 # along with GNU Radio; see the file COPYING. If not, write to
18 # the Free Software Foundation, Inc., 51 Franklin Street,
19 # Boston, MA 02110-1301, USA.
23 # Generating Python docstrings from C++ code using doxygen
26 There are at least two strategies for this:
27 - use xsltproc as described below
28 - use doxy2swig.py (included in this directory)
30 FIXME: get one of these working (probably doxy2swig since it doesn't
31 add any additional dependencies).
33 ----------------------------------------------------------------
35 Note: Robin's patch is in SWIG >= 1.3.23
37 --------------------------------------------------------------------------------
38 From: http://mailman.cs.uchicago.edu/pipermail/swig/2004-October/010604.html
40 > I applied the docstring patch. '%feature("autodoc",1");' is working as
45 > I can not agree more with the doxygen idea. I am using doxygen for
46 > documentation and I have been trying to put doxygen output to the
47 > python interface. Automatic generation of %feature("docstring") lines
48 > from doxygen output is the closest solution I can think of but the
49 > workload is still pretty big. How I wish this feature can be
50 > implemented in the near future.
52 I have successfully extracted function/class description from doxygen
53 generated xml files, using an xslt script. To add doxygen generated
54 description to each class/function, you will need to (tested under
55 linux, note that this works only for Python, using Robin's docstring
58 1. download swig source, apply Robin's docstring patch from
59 https://sourceforge.net/tracker/index.php?func=detail&aid=1023309&group_id=1645&atid=301645
62 2. generate doxygen document with option "GENERATE_XML = YES"
64 3. copy the attached script (save as swig.xsl) to the doc/xml directory
67 > xsltproc swig.xsl index.xml > temp_doc.i
68 > cat temp_doc.i | sed 's/"/\\"/g' | sed 's/__QuOtE__/"/g' > swig_doc.i
70 you will get an interface file with lines like
71 %feature("docstring") class "class description";
72 %feature("docstring") class::function "member function
75 the second step is necessary since there might be " in descriptions
76 and I need to backquote them before I replace __QuOtE__ by real
77 quotes. (xslt experts may know how to post-process <xsl:value-of> and
78 make the script easier to use.)
80 4. in your interface file, add
82 %feature("autodoc","1") ;
87 =========================================================
89 <!-- XSLT script to extract document for class/function for swig docstring
90 If you have xsltproc you could use:
91 xsltproc swig.xsl index.xml > swig_doc.i
93 <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
94 <xsl:output method="text"/>
95 <xsl:template match="/">
96 <!-- process each compound -->
97 <xsl:for-each select="doxygenindex/compound">
98 <xsl:apply-templates select="document( concat( @refid, '.xml' ) )/*" />
102 <xsl:template match="doxygen">
103 <xsl:for-each select="compounddef[@kind='class']">
104 <xsl:text>%feature(__QuOtE__docstring__QuOtE__) </xsl:text>
105 <xsl:value-of select="compoundname"/>
106 <xsl:text> __QuOtE__ </xsl:text>
107 <xsl:value-of select="briefdescription"/><xsl:text>
109 <xsl:value-of select="detaileddescription"/>
110 <xsl:text> see also: </xsl:text>
111 <xsl:value-of select="includes"/>
112 <xsl:text>__QuOtE__; </xsl:text>
114 <!-- output for each function individually -->
115 <xsl:for-each select="*/memberdef[@kind='function' and not(starts-with(name,'operator'))]">
116 <xsl:text>%feature(__QuOtE__docstring__QuOtE__) </xsl:text><xsl:value-of select="../../compoundname"/>::<xsl:value-of select="name"/>
117 <xsl:text> __QuOtE__ </xsl:text>
118 <xsl:value-of select="definition"/> <xsl:value-of select="argsstring"/>
120 </xsl:text><xsl:value-of select="briefdescription"/><xsl:text>
121 </xsl:text><xsl:value-of select="detaileddescription"/>
122 <xsl:text>__QuOtE__; </xsl:text>