From 349331a884594a9e242231bffb03112b8943883c Mon Sep 17 00:00:00 2001
From: eb
Date: Thu, 14 May 2009 18:29:26 +0000
Subject: Doc fixes.  Merged eb/t367 -r11020:11025 to trunk.  This changeset
 moves the primary doxygen configuration under the top-level docs directory. 
 It creates a new "docs" top-level component that can be enabled/disabled
 using the configure --disable-docs option.  At this time, the
 --enable-doxygen option is still required to enable the generation of the
 doxygen documents.  I think the flag should probably be removed, and default
 to "yes" if we find doxygen on the path.  The user can disable the doc
 generation using --disable-docs if desired.

The doxygen config file has been modified such that doxygen is now
only run on the C++ sources.  No attempt is made to process the python
code using doxygen.  This results in a less confusing set of docs for
the the C++ API.  Straightening out the python docs is left for later.

Many classes are currently misclassified (\ingroup <wrong>).  That
will probably require another day of work, that I can't get to right now.



git-svn-id: http://gnuradio.org/svn/gnuradio/trunk@11027 221aa14e-8319-0410-a670-987f0aec2ac5
---
 docs/doxygen/xml-swig/README | 129 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 129 insertions(+)
 create mode 100644 docs/doxygen/xml-swig/README

(limited to 'docs/doxygen/xml-swig/README')

diff --git a/docs/doxygen/xml-swig/README b/docs/doxygen/xml-swig/README
new file mode 100644
index 000000000..e5187df28
--- /dev/null
+++ b/docs/doxygen/xml-swig/README
@@ -0,0 +1,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__ &#10;</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__;&#10;&#10;</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__&#10;</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__; &#10;&#10;</xsl:text>
+      </xsl:for-each>
+    </xsl:for-each>  
+  </xsl:template>
+</xsl:stylesheet>
+
+--
+Bo Peng
\ No newline at end of file
-- 
cgit