git.gag.com Git - debian/gnuradio/blob - docs/doxygen/xml-swig/README

   1 #
   2 # Copyright 2005 Free Software Foundation, Inc.
   3 #
   4 # This file is part of GNU Radio
   5 #
   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 3, or (at your option)
   9 # any later version.
  10 #
  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.
  15 #
  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.
  20 #
  21
  22 #
  23 # Generating Python docstrings from C++ code using doxygen
  24 #
  25
  26 There are at least two strategies for this:
  27   - use xsltproc as described below
  28   - use doxy2swig.py (included in this directory)
  29
  30 FIXME: get one of these working (probably doxy2swig since it doesn't
  31 add any additional dependencies).
  32
  33 ----------------------------------------------------------------
  34
  35 Note: Robin's patch is in SWIG >= 1.3.23
  36
  37 --------------------------------------------------------------------------------
  38 From: http://mailman.cs.uchicago.edu/pipermail/swig/2004-October/010604.html
  39
  40 > I applied the docstring patch. '%feature("autodoc",1");' is working as
  41 > expected ...
  42
  43 [problem solved. ...]
  44
  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.
  51
  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
  56 patch)
  57
  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
  60    compile and install
  61
  62 2. generate doxygen document with option "GENERATE_XML = YES"
  63
  64 3. copy the attached script (save as swig.xsl) to the doc/xml directory
  65    and run
  66
  67      > xsltproc swig.xsl index.xml > temp_doc.i
  68      > cat temp_doc.i | sed 's/"/\\"/g' | sed 's/__QuOtE__/"/g' > swig_doc.i
  69
  70    you will get an interface file with lines like
  71      %feature("docstring") class "class description";
  72      %feature("docstring") class::function "member function
  73          description";
  74
  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.)
  79
  80 4. in your interface file, add
  81      %include "siwg_doc.i"
  82      %feature("autodoc","1") ;
  83
  84 Hope this helps.
  85
  86 swig.xsl:
  87 =========================================================
  88
  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
  92 -->
  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' ) )/*" />
  99       </xsl:for-each>
 100    </xsl:template>
 101
 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__ &#10;</xsl:text>
 107       <xsl:value-of select="briefdescription"/><xsl:text>
 108       </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__;&#10;&#10;</xsl:text>
 113
 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__&#10;</xsl:text>
 118         <xsl:value-of select="definition"/> <xsl:value-of select="argsstring"/>
 119         <xsl:text>
 120         </xsl:text><xsl:value-of select="briefdescription"/><xsl:text>
 121         </xsl:text><xsl:value-of select="detaileddescription"/>
 122         <xsl:text>__QuOtE__; &#10;&#10;</xsl:text>
 123       </xsl:for-each>
 124     </xsl:for-each>
 125   </xsl:template>
 126 </xsl:stylesheet>
 127
 128 --
 129 Bo Peng