1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
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
|
