Merge branch 'master' into gr_log

Conflicts: CMakeLists.txt cmake/Modules/GrMiscUtils.cmake docs/doxygen/other/build_guide.dox gnuradio-core/CMakeLists.txt gr-digital/lib/CMakeLists.txt
author: Tom Rondeau <trondeau@vt.edu> 2012-09-06 12:01:23 -0400
committer: Tom Rondeau <trondeau@vt.edu> 2012-09-06 12:01:23 -0400
commit: c9dc582402d2551ead29a60256fdf64a1d43534c (patch)
tree: 4e9fe56c173a8e080c84c4c113a5ac5c5f1c236c /docs/doxygen
parent: 1300d48af4752037feac4fae7c3c64187cc0a5a8 (diff)
parent: a4e2e8a9a2c8a6bbd6d676a17b0e2732e11af09f (diff)
6 files changed, 361 insertions, 299 deletions
diff --git a/docs/doxygen/Doxyfile.in b/docs/doxygen/Doxyfile.in
index f3485316c4..ad3c2d01f4 100644
--- a/docs/doxygen/Doxyfile.in
+++ b/docs/doxygen/Doxyfile.in
@@ -628,7 +628,6 @@ EXCLUDE                = @abs_top_builddir@/docs/doxygen/html \
                          @abs_top_builddir@/gr-gsm-fr-vocoder/src/lib/gsm_full_rate.py \
                          @abs_top_builddir@/gr-gsm-fr-vocoder/src/python/encdec.py \
                          @abs_top_builddir@/gr-howto-write-a-block \
-                         @abs_top_builddir@/gr-howto-write-a-block-cmake \
                          @abs_top_builddir@/gr-pager/src/pager_swig.py \
                          @abs_top_builddir@/gr-trellis/doc \
                          @abs_top_builddir@/gr-trellis/src/lib/generate_all.py \
@@ -640,7 +639,7 @@ EXCLUDE                = @abs_top_builddir@/docs/doxygen/html \
 			 @abs_top_builddir@/_CPack_Packages \
                          @abs_top_srcdir@/cmake \
 			 @abs_top_srcdir@/gr-qtgui/lib \
-                         @abs_top_srcdir@/gr-howto-write-a-block-cmake
+                         @abs_top_srcdir@/gr-howto-write-a-block
 
 # The EXCLUDE_SYMLINKS tag can be used select whether or not files or
 # directories that are symbolic links (a Unix filesystem feature) are excluded
diff --git a/docs/doxygen/doxyxml/doxyindex.py b/docs/doxygen/doxyxml/doxyindex.py
index 0132ab86fd..304109a8e5 100644
--- a/docs/doxygen/doxyxml/doxyindex.py
+++ b/docs/doxygen/doxyxml/doxyindex.py
@@ -1,23 +1,23 @@
 #
 # Copyright 2010 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.
-#
+# 
 """
 Classes providing more user-friendly interfaces to the doxygen xml
 docs than the generated classes provide.
@@ -40,7 +40,7 @@ class DoxyIndex(Base):
         if self._parsed:
             return
         super(DoxyIndex, self)._parse()
-        self._root = index.parse(os.path.join(self._xml_path, 'index.xml'))
+        self._root = index.parse(os.path.join(self._xml_path, 'index.xml'))      
         for mem in self._root.compound:
             converted = self.convert_mem(mem)
             # For files we want the contents to be accessible directly
@@ -78,7 +78,24 @@ class DoxyCompMem(Base):
         bd = description(getattr(parse_data, 'briefdescription', None))
         dd = description(getattr(parse_data, 'detaileddescription', None))
         self._data['brief_description'] = bd
-        self._data['detailed_description'] = dd
+        self._data['detailed_description'] = dd        
+
+    def set_parameters(self, data):
+        vs = [ddc.value for ddc in data.detaileddescription.content_]
+        pls = []
+        for v in vs:
+            if hasattr(v, 'parameterlist'):
+                pls += v.parameterlist
+        pis = []
+        for pl in pls:
+            pis += pl.parameteritem
+        dpis = []
+        for pi in pis:
+            dpi = DoxyParameterItem(pi)
+            dpi._parse()
+            dpis.append(dpi)
+        self._data['params'] = dpis
+
 
 class DoxyCompound(DoxyCompMem):
     pass
@@ -86,7 +103,6 @@ class DoxyCompound(DoxyCompMem):
 class DoxyMember(DoxyCompMem):
     pass
 
-
 class DoxyFunction(DoxyMember):
 
     __module__ = "gnuradio.utils.doxyxml"
@@ -98,10 +114,13 @@ class DoxyFunction(DoxyMember):
             return
         super(DoxyFunction, self)._parse()
         self.set_descriptions(self._parse_data)
-        self._data['params'] = []
-        prms = self._parse_data.param
-        for prm in prms:
-            self._data['params'].append(DoxyParam(prm))
+        self.set_parameters(self._parse_data)
+        if not self._data['params']:
+            # If the params weren't set by a comment then just grab the names.
+            self._data['params'] = []
+            prms = self._parse_data.param
+            for prm in prms:
+                self._data['params'].append(DoxyParam(prm))
 
     brief_description = property(lambda self: self.data()['brief_description'])
     detailed_description = property(lambda self: self.data()['detailed_description'])
@@ -111,7 +130,7 @@ Base.mem_classes.append(DoxyFunction)
 
 
 class DoxyParam(DoxyMember):
-
+    
     __module__ = "gnuradio.utils.doxyxml"
 
     def _parse(self):
@@ -121,16 +140,46 @@ class DoxyParam(DoxyMember):
         self.set_descriptions(self._parse_data)
         self._data['declname'] = self._parse_data.declname
 
+    @property
+    def description(self):
+        descriptions = []
+        if self.brief_description:
+            descriptions.append(self.brief_description)
+        if self.detailed_description:
+            descriptions.append(self.detailed_description)
+        return '\n\n'.join(descriptions)
+
     brief_description = property(lambda self: self.data()['brief_description'])
     detailed_description = property(lambda self: self.data()['detailed_description'])
-    declname = property(lambda self: self.data()['declname'])
+    name = property(lambda self: self.data()['declname'])
 
-class DoxyClass(DoxyCompound):
+class DoxyParameterItem(DoxyMember):
+    """A different representation of a parameter in Doxygen."""
+
+    def _parse(self):
+        if self._parsed:
+            return
+        super(DoxyParameterItem, self)._parse()
+        names = []
+        for nl in self._parse_data.parameternamelist:
+            for pn in nl.parametername:
+                names.append(description(pn))
+        # Just take first name
+        self._data['name'] = names[0]
+        # Get description
+        pd = description(self._parse_data.get_parameterdescription())
+        self._data['description'] = pd
+
+    description = property(lambda self: self.data()['description'])
+    name = property(lambda self: self.data()['name'])
 
+
+class DoxyClass(DoxyCompound):
+    
     __module__ = "gnuradio.utils.doxyxml"
 
     kind = 'class'
-
+    
     def _parse(self):
         if self._parsed:
             return
@@ -139,22 +188,24 @@ class DoxyClass(DoxyCompound):
         if self._error:
             return
         self.set_descriptions(self._retrieved_data.compounddef)
+        self.set_parameters(self._retrieved_data.compounddef)
         # Sectiondef.kind tells about whether private or public.
         # We just ignore this for now.
         self.process_memberdefs()
 
     brief_description = property(lambda self: self.data()['brief_description'])
     detailed_description = property(lambda self: self.data()['detailed_description'])
+    params = property(lambda self: self.data()['params'])
 
 Base.mem_classes.append(DoxyClass)
-
+        
 
 class DoxyFile(DoxyCompound):
-
+    
     __module__ = "gnuradio.utils.doxyxml"
 
     kind = 'file'
-
+    
     def _parse(self):
         if self._parsed:
             return
@@ -164,7 +215,7 @@ class DoxyFile(DoxyCompound):
         if self._error:
             return
         self.process_memberdefs()
-
+        
     brief_description = property(lambda self: self.data()['brief_description'])
     detailed_description = property(lambda self: self.data()['detailed_description'])
 
@@ -172,16 +223,16 @@ Base.mem_classes.append(DoxyFile)
 
 
 class DoxyNamespace(DoxyCompound):
-
+    
     __module__ = "gnuradio.utils.doxyxml"
 
     kind = 'namespace'
-
+    
 Base.mem_classes.append(DoxyNamespace)
 
 
 class DoxyGroup(DoxyCompound):
-
+    
     __module__ = "gnuradio.utils.doxyxml"
 
     kind = 'group'
@@ -209,7 +260,7 @@ class DoxyGroup(DoxyCompound):
         self.process_memberdefs()
 
     title = property(lambda self: self.data()['title'])
-
+        
 
 Base.mem_classes.append(DoxyGroup)
 
@@ -224,7 +275,7 @@ Base.mem_classes.append(DoxyFriend)
 
 
 class DoxyOther(Base):
-
+    
     __module__ = "gnuradio.utils.doxyxml"
 
     kinds = set(['variable', 'struct', 'union', 'define', 'typedef', 'enum', 'dir', 'page'])
@@ -232,6 +283,6 @@ class DoxyOther(Base):
     @classmethod
     def can_parse(cls, obj):
         return obj.kind in cls.kinds
-
+    
 Base.mem_classes.append(DoxyOther)
 
diff --git a/docs/doxygen/other/build_guide.dox b/docs/doxygen/other/build_guide.dox
deleted file mode 100644
index fe4b44f345..0000000000
--- a/docs/doxygen/other/build_guide.dox
+++ /dev/null
@@ -1,170 +0,0 @@
-/*! \page page_build Build Instructions and Information
-
-\section dependencies Dependencies
-
-The list of GNU Radio dependencies and the minimum required versions,
-if any, to build the various GNU Radio components.
-
-Most of these components do not need to be individually compiled or
-installed. Instead, rely on your operating system's package manager or
-binary installation process (the <b>apt-get</b> system in Debian and
-Ubuntu, <b>yum</b> in RedHat and Fedora, etc.). GNU Radio tries to keep an
-up-to-date build guide for the majority of the supported operating
-systems on gnuradio.org
-(http://gnuradio.org/redmine/projects/gnuradio/wiki/BuildGuide).
-
-Not all dependencies are required for all components, and not all
-components are required for a given installation. The list of required
-components is determined by what the user requires from GNU Radio. If,
-for example, you do not use any Comedi-based hardware, do not worry
-about building gr-comedi.
-
-\subsection dep_global Global Dependencies
-\li git                      http://code.google.com/p/msysgit
-\li cmake       (>= 2.6)     http://www.cmake.org/cmake/resources/software.html
-\li boost       (>= 1.35)    http://www.boostpro.com/download
-\li cppunit     (>= 1.9.14)  http://gaiacrtn.free.fr/cppunit/index.html
-\li fftw3f      (>= 3.0)     http://www.fftw.org/install/windows.html
-\li gsl	        (>= 1.10)    http://gnuwin32.sourceforge.net/packages/gsl.htm
-
-\subsection dep_python Python Wrappers
-\li python      (>= 2.5)     http://www.python.org/download/
-\li swig        (>= 1.3.31)  http://www.swig.org/download.html
-\li numpy       (>= 1.1.0)   http://sourceforge.net/projects/numpy/files/NumPy/
-
-\subsection dep_docs docs: Building the documentation
-\li doxygen     (>= 1.5)     http://www.stack.nl/~dimitri/doxygen/download.html
-
-\subsection dep_grc grc: The GNU Radio Companion
-\li Cheetah     (>= 2.0)     http://www.cheetahtemplate.org/
-\li pygtk       (>= 2.10)    http://www.pygtk.org/downloads.html
-
-\subsection dep_gr_qtgui gr-qtgui: The QT-based Graphical User Interface
-\li qt	        (>= 4.4)     http://qt.nokia.com/downloads/
-\li qwt         (>= 5.2)     http://sourceforge.net/projects/qwt/
-\li pyqt        (>= 4.4)     http://www.riverbankcomputing.co.uk/software/pyqt/download
-\li pyqwt       (>= 5.2)     http://pyqwt.sourceforge.net/download.html
-
-\subsection dep_gr_wxgui gr-wxgui: The WX-based Graphical User Interface
-\li wxpython    (>= 2.8)     http://www.wxpython.org/
-\li python-lxml (>= 1.3.6)   http://lxml.de/
-
-\subsection dep_gr_audio gr-audio: Audio Subsystems (system/OS dependent)
-\li audio-alsa  (>= 0.9)     http://www.alsa-project.org
-\li audio-jack  (>= 0.8)     http://jackaudio.org/
-\li portaduio   (>= 19)      http://www.portaudio.com/
-\li audio-oss   (>= 1.0)     http://www.opensound.com/oss.html
-\li audio-osx
-\li audio-windows
-
-\subsection dep_uhd uhd: The Ettus USRP Hardware Driver Interface
-\li uhd         (>= 3.0.0)   http://code.ettus.com/redmine/ettus/projects/uhd/wiki
-
-\subsection dep_shd shd: The Symplex Hardware Driver Interface
-\li shd         (>= 3.0.0)
-
-\subsection dep_gr_video_sdl gr-video-sdl: PAL and NTSC display
-\li SDL	        (>= 1.2.0)   http://www.libsdl.org/download-1.2.php
-
-\subsection dep_gr_comedi gr-comedi: Comedi hardware interface
-\li comedilib   (>= 0.8)     http://www.comedi.org/
-
-\subsection dep_gr_log gr-log: Logging Tools (Optional)
-\li log4cxx     (>= 0.10.0)  http://logging.apache.org/log4cxx
-
-
-\section build_gr_cmake Building GNU Radio
-
-GNU Radio is built using the Cmake build system
-(http://www.cmake.org/). The standard build method is as follows:
-
-\code
-$ mkdir $(builddir)
-$ cd $(builddir)
-$ cmake [OPTIONS] $(srcdir)
-$ make
-$ make test
-$ sudo make install
-\endcode
-
-The \$(builddir) is the directory in which the code is built. This
-<b>cannot</b> be the same path as where the source code resides. Often,
-\$(builddir) is \$(srcdir)/build.
-
-\subsection Cmake Options
-
-Options can be used to specify where to find various library or
-include file dependencies that are not automatically being found
-(-DCMAKE_PREFIX_PATH) or set the prefix
-(-DCMAKE_INSTALL_PREFIX=(dir)).
-
-Components can also be enabled and disabled through the options. For a
-component named *gr-comp*, the option to disable would look like:
--DENABLE_GR_COMP=off. The "off" could also be "false" or "no", and
-cmake is not case sensitive about these options. Similarly, "true",
-"on", or "yes" will turn this component on. All components are enabled
-by default.
-
-An example is -DENABLE_PYTHON=False turns off building any Python or
-Swigging components. The result will be the GNU Radio libraries and
-C++ programs/applications/examples. No Python or GRC files will be
-built or installed.
-
-The -DENABLE_DEFAULT=False can be used to disable all
-components. Individual components can then be selectively turned back
-on. For example, just buidling the Volk and Gruel libraries can be
-done with this:
-
-\code
-cmake -DENABLE_DEFAULT=Off -DENABLE_VOLK=True -DENABLE_GRUEL=True <srcdir>
-\endcode
-
-
-The build type allows you to specify the build as a debug or release
-version. Each type sets different flags for different purposes. To set
-the build type, use:
-
-\code
--DCMAKE_BUILD_TYPE="Release"|"Debug"
-\endcode
-
-If not specified, the "Release" mode is the defaulted to.
-
-"Release" mode sets the '-O3' optimization flag.
-
-"Debug" mode sets '-g -O2' flags to export debug symbols and reduce
-the optimization to make the libraries easier to debug and step
-through.
-
-
-\subsection build_gr_cmake_e100 Building for the E100
-
-To build GNU Radio on the Ettus Research E100 embedded platforms,
-Cmake has to know that the processors uses the NEON extensions. Use
-the
-
-\code
-cmake -DCMAKE_CXX_FLAGS:STRING="-mcpu=cortex-a8 -mfpu=neon -mfloat-abi=softfp -g" \
-      -DCMAKE_C_FLAGS:STRING="-mcpu=cortex-a8 -mfpu=neon -mfloat-abi=softfp -g" \
-       <gr_source_dir>
-\endcode
-
-
-\section build_old_autotools Building Using Old Autotools Method
-
-As of version 3.5, we have moved to using Cmake as the default,
-preferred build system. If for some reason, Cmake fails on your
-system, GNU Radio still includes the old autotools build process as a
-parallel build method. To build:
-
-\code
-$ cd $(srcdir)
-$ ./bootstrap   // only if not building from a tarball
-$ cd $(builddir)
-$ $(srcdir)/configure [options]
-$ make [-jN]
-$ make check
-$ sudo make install
-\endcode
-
-*/
diff --git a/docs/doxygen/other/volk_guide.dox b/docs/doxygen/other/extra_pages.dox
index 24882ed1a6..d40c692e03 100644
--- a/docs/doxygen/other/volk_guide.dox
+++ b/docs/doxygen/other/extra_pages.dox
@@ -1,3 +1,166 @@
+/*! \page build_guide Build Instructions and Information
+
+\section dependencies Dependencies
+
+The list of GNU Radio dependencies and the minimum required versions,
+if any, to build the various GNU Radio components.
+
+Most of these components do not need to be individually compiled or
+installed. Instead, rely on your operating system's package manager or
+binary installation process (the <b>apt-get</b> system in Debian and
+Ubuntu, <b>yum</b> in RedHat and Fedora, etc.). GNU Radio tries to keep an
+up-to-date build guide for the majority of the supported operating
+systems on gnuradio.org
+(http://gnuradio.org/redmine/projects/gnuradio/wiki/BuildGuide).
+
+Not all dependencies are required for all components, and not all
+components are required for a given installation. The list of required
+components is determined by what the user requires from GNU Radio. If,
+for example, you do not use any Comedi-based hardware, do not worry
+about building gr-comedi.
+
+Before trying to build these from source, please try your system's
+installation tool (apt-get, pkg_install, YaST, yum, urpmi, etc.)
+first. Most recent systems have these packages available.
+
+\subsection dep_global Global Dependencies
+\li git                      http://code.google.com/p/msysgit
+\li cmake       (>= 2.6)     http://www.cmake.org/cmake/resources/software.html
+\li boost       (>= 1.35)    http://www.boostpro.com/download
+\li cppunit     (>= 1.9.14)  http://gaiacrtn.free.fr/cppunit/index.html
+\li fftw3f      (>= 3.0)     http://www.fftw.org/install/windows.html
+
+\subsection dep_python Python Wrappers
+\li python      (>= 2.5)     http://www.python.org/download/
+\li swig        (>= 1.3.31)  http://www.swig.org/download.html
+\li numpy       (>= 1.1.0)   http://sourceforge.net/projects/numpy/files/NumPy/
+
+\subsection dep_docs docs: Building the documentation
+\li doxygen     (>= 1.5)     http://www.stack.nl/~dimitri/doxygen/download.html
+
+\subsection dep_grc grc: The GNU Radio Companion
+\li Cheetah     (>= 2.0)     http://www.cheetahtemplate.org/
+\li pygtk       (>= 2.10)    http://www.pygtk.org/downloads.html
+
+\subsection dep_wavelet gr-wavelet: Collection of wavelet blocks
+\li gsl	        (>= 1.10)    http://gnuwin32.sourceforge.net/packages/gsl.htm
+
+\subsection dep_gr_qtgui gr-qtgui: The QT-based Graphical User Interface
+\li qt	        (>= 4.4)     http://qt.nokia.com/downloads/
+\li qwt         (>= 5.2)     http://sourceforge.net/projects/qwt/
+\li pyqt        (>= 4.4)     http://www.riverbankcomputing.co.uk/software/pyqt/download
+\li pyqwt       (>= 5.2)     http://pyqwt.sourceforge.net/download.html
+
+\subsection dep_gr_wxgui gr-wxgui: The WX-based Graphical User Interface
+\li wxpython    (>= 2.8)     http://www.wxpython.org/
+\li python-lxml (>= 1.3.6)   http://lxml.de/
+
+\subsection dep_gr_audio gr-audio: Audio Subsystems (system/OS dependent)
+\li audio-alsa  (>= 0.9)     http://www.alsa-project.org
+\li audio-jack  (>= 0.8)     http://jackaudio.org/
+\li portaduio   (>= 19)      http://www.portaudio.com/
+\li audio-oss   (>= 1.0)     http://www.opensound.com/oss.html
+\li audio-osx
+\li audio-windows
+
+It is not necessary to satisfy all of these dependencies; just the
+one(s) that are right for your system. On Linux, don't expect
+audio-osx and audio-windows to be either satisfied or built.
+
+\subsection dep_uhd uhd: The Ettus USRP Hardware Driver Interface
+\li uhd         (>= 3.0.0)   http://code.ettus.com/redmine/ettus/projects/uhd/wiki
+
+\subsection dep_shd shd: The Symplex Hardware Driver Interface
+\li shd         (>= 3.0.0)
+
+\subsection dep_gr_video_sdl gr-video-sdl: PAL and NTSC display
+\li SDL	        (>= 1.2.0)   http://www.libsdl.org/download-1.2.php
+
+\subsection dep_gr_comedi gr-comedi: Comedi hardware interface
+\li comedilib   (>= 0.8)     http://www.comedi.org/
+
+
+
+\section build_gr_cmake Building GNU Radio
+
+GNU Radio is built using the Cmake build system
+(http://www.cmake.org/). The standard build method is as follows:
+
+\code
+$ mkdir $(builddir)
+$ cd $(builddir)
+$ cmake [OPTIONS] $(srcdir)
+$ make
+$ make test
+$ sudo make install
+\endcode
+
+The \$(builddir) is the directory in which the code is built. This
+<b>cannot</b> be the same path as where the source code resides. Often,
+\$(builddir) is \$(srcdir)/build.
+
+\subsection Cmake Options
+
+Options can be used to specify where to find various library or
+include file dependencies that are not automatically being found
+(-DCMAKE_PREFIX_PATH) or set the prefix
+(-DCMAKE_INSTALL_PREFIX=(dir)).
+
+Components can also be enabled and disabled through the options. For a
+component named *gr-comp*, the option to disable would look like:
+-DENABLE_GR_COMP=off. The "off" could also be "false" or "no", and
+cmake is not case sensitive about these options. Similarly, "true",
+"on", or "yes" will turn this component on. All components are enabled
+by default.
+
+An example is -DENABLE_PYTHON=False turns off building any Python or
+Swigging components. The result will be the GNU Radio libraries and
+C++ programs/applications/examples. No Python or GRC files will be
+built or installed.
+
+The -DENABLE_DEFAULT=False can be used to disable all
+components. Individual components can then be selectively turned back
+on. For example, just buidling the Volk and Gruel libraries can be
+done with this:
+
+\code
+cmake -DENABLE_DEFAULT=Off -DENABLE_VOLK=True -DENABLE_GRUEL=True <srcdir>
+\endcode
+
+
+The build type allows you to specify the build as a debug or release
+version. Each type sets different flags for different purposes. To set
+the build type, use:
+
+\code
+-DCMAKE_BUILD_TYPE="Release"|"Debug"
+\endcode
+
+If not specified, the "Release" mode is the defaulted to.
+
+"Release" mode sets the '-O3' optimization flag.
+
+"Debug" mode sets '-g -O2' flags to export debug symbols and reduce
+the optimization to make the libraries easier to debug and step
+through.
+
+
+\subsection build_gr_cmake_e100 Building for the E100
+
+To build GNU Radio on the Ettus Research E100 embedded platforms,
+Cmake has to know that the processors uses the NEON extensions. Use
+the
+
+\code
+cmake -DCMAKE_CXX_FLAGS:STRING="-mcpu=cortex-a8 -mfpu=neon -mfloat-abi=softfp -g" \
+      -DCMAKE_C_FLAGS:STRING="-mcpu=cortex-a8 -mfpu=neon -mfloat-abi=softfp -g" \
+       <gr_source_dir>
+\endcode
+
+*/
+
+
+
 /*! \page volk_guide Instructions for using Volk in GNU Radio
 
 \section volk_intro Introduction
@@ -63,7 +226,7 @@ calls with:
 \code
   const int alignment_multiple =
     volk_get_alignment() / output_item_size;
-  set_alignment(alignment_multiple);
+  set_alignment(std::max(1,alignment_multiple));
 \endcode
 
 The Volk function 'volk_get_alignment' provides the alignment of the
@@ -159,3 +322,5 @@ volk_config file that sets all architectures to 'generic' as a way to
 test the vectorized versus non-vectorized implementations.
 
 */
+
+
diff --git a/docs/doxygen/other/main_page.dox b/docs/doxygen/other/main_page.dox
index cd948c3058..c5d5a44cb7 100644
--- a/docs/doxygen/other/main_page.dox
+++ b/docs/doxygen/other/main_page.dox
@@ -14,7 +14,7 @@ the <a href="http://gnuradio.squarespace.com" target="_blank"><b>GNU Radio blog<
 
 \section build Building GNU Radio
 
-See the \ref page_build page for details about the project's
+See the \ref build_guide page for details about the project's
 dependencies and build process.
 
 
diff --git a/docs/doxygen/swig_doc.py b/docs/doxygen/swig_doc.py
index bd35b8efdd..f24608b3ee 100644
--- a/docs/doxygen/swig_doc.py
+++ b/docs/doxygen/swig_doc.py
@@ -1,23 +1,23 @@
 #
-# Copyright 2010,2011 Free Software Foundation, Inc.
-#
+# Copyright 2010-2012 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.
-#
+# 
 """
 Creates the swig_doc.i SWIG interface file.
 Execute using: python swig_doc.py xml_path outputfilename
@@ -29,11 +29,8 @@ python docstrings.
 
 import sys, time
 
-try:
-    from doxyxml import DoxyIndex, DoxyClass, DoxyFriend, DoxyFunction, DoxyFile, base
-except ImportError:
-    from gnuradio.doxyxml import DoxyIndex, DoxyClass, DoxyFriend, DoxyFunction, DoxyFile, base
-
+from doxyxml import DoxyIndex, DoxyClass, DoxyFriend, DoxyFunction, DoxyFile
+from doxyxml import DoxyOther, base
 
 def py_name(name):
     bits = name.split('_')
@@ -56,8 +53,29 @@ class Block(object):
         # Check for a parsing error.
         if item.error():
             return False
-        return item.has_member(make_name(item.name()), DoxyFriend)
-
+        friendname = make_name(item.name())
+        is_a_block = item.has_member(friendname, DoxyFriend)
+        # But now sometimes the make function isn't a friend so check again.
+        if not is_a_block:
+            is_a_block = di.has_member(friendname, DoxyFunction)
+        return is_a_block
+
+class Block2(object):
+    """
+    Checks if doxyxml produced objects correspond to a new style
+    gnuradio block.
+    """
+    
+    @classmethod
+    def includes(cls, item):
+        if not isinstance(item, DoxyClass):
+            return False
+        # Check for a parsing error.
+        if item.error():
+            return False
+        is_a_block2 = item.has_member('make', DoxyFunction) and item.has_member('sptr', DoxyOther)
+        return is_a_block2
+        
 
 def utoascii(text):
     """
@@ -82,13 +100,19 @@ def combine_descriptions(obj):
     if dd:
         description.append(dd)
     return utoascii('\n\n'.join(description)).strip()
-
+    
+def format_params(parameteritems):
+    output = ['Args:']
+    template = '    {0} : {1}'
+    for pi in parameteritems:
+        output.append(template.format(pi.name, pi.description))
+    return '\n'.join(output)
 
 entry_templ = '%feature("docstring") {name} "{docstring}"'
-def make_entry(obj, name=None, templ="{description}", description=None):
+def make_entry(obj, name=None, templ="{description}", description=None, params=[]):
     """
     Create a docstring entry for a swig interface file.
-
+    
     obj - a doxyxml object from which documentation will be extracted.
     name - the name of the C object (defaults to obj.name())
     templ - an optional template for the docstring containing only one
@@ -102,6 +126,9 @@ def make_entry(obj, name=None, templ="{description}", description=None):
         return ''
     if description is None:
         description = combine_descriptions(obj)
+    if params:
+        description += '\n\n'
+        description += utoascii(format_params(params))
     docstring = templ.format(description=description)
     if not docstring:
         return ''
@@ -121,27 +148,31 @@ def make_func_entry(func, name=None, description=None, params=None):
             used as the description instead of extracting it from func.
     params - a parameter list that overrides using func.params.
     """
-    if params is None:
-        params = func.params
-    params = [prm.declname for prm in params]
-    if params:
-        sig = "Params: (%s)" % ", ".join(params)
-    else:
-        sig = "Params: (NONE)"
-    templ = "{description}\n\n" + sig
-    return make_entry(func, name=name, templ=utoascii(templ),
-                      description=description)
-
-
-def make_class_entry(klass, description=None):
+    #if params is None:
+    #    params = func.params
+    #params = [prm.declname for prm in params]
+    #if params:
+    #    sig = "Params: (%s)" % ", ".join(params)
+    #else:
+    #    sig = "Params: (NONE)"
+    #templ = "{description}\n\n" + sig
+    #return make_entry(func, name=name, templ=utoascii(templ),
+    #                  description=description)
+    return make_entry(func, name=name, description=description, params=params)
+
+
+def make_class_entry(klass, description=None, ignored_methods=[], params=None):
     """
     Create a class docstring for a swig interface file.
     """
+    if params is None:
+        params = klass.params
     output = []
-    output.append(make_entry(klass, description=description))
+    output.append(make_entry(klass, description=description, params=params))
     for func in klass.in_category(DoxyFunction):
-        name = klass.name() + '::' + func.name()
-        output.append(make_func_entry(func, name=name))
+        if func.name() not in ignored_methods:
+            name = klass.name() + '::' + func.name()
+            output.append(make_func_entry(func, name=name))
     return "\n\n".join(output)
 
 
@@ -175,18 +206,38 @@ def make_block_entry(di, block):
     # the make function.
     output = []
     output.append(make_class_entry(block, description=super_description))
-    creator = block.get_member(block.name(), DoxyFunction)
     output.append(make_func_entry(make_func, description=super_description,
-                                  params=creator.params))
+                                  params=block.params))
     return "\n\n".join(output)
 
+def make_block2_entry(di, block):
+    """
+    Create class and function docstrings of a new style gnuradio block for a
+    swig interface file.
+    """
+    descriptions = []
+    # For new style blocks all the relevant documentation should be
+    # associated with the 'make' method.
+    make_func = block.get_member('make', DoxyFunction)
+    description = combine_descriptions(make_func)
+    # Associate the combined description with the class and
+    # the make function.
+    output = []
+    #output.append(make_class_entry(
+    #        block, description=description,
+    #        ignored_methods=['make'], params=make_func.params))
+    makename = block.name() + '::make'
+    output.append(make_func_entry(
+            make_func, name=makename, description=description,
+            params=make_func.params))
+    return "\n\n".join(output)
 
 def make_swig_interface_file(di, swigdocfilename, custom_output=None):
-
+    
     output = ["""
 /*
  * This file was automatically generated using swig_doc.py.
- *
+ * 
  * Any changes to it will be lost next time it is regenerated.
  */
 """]
@@ -195,67 +246,53 @@ def make_swig_interface_file(di, swigdocfilename, custom_output=None):
         output.append(custom_output)
 
     # Create docstrings for the blocks.
-    tries = 0
-    while(1):
-        try:
-            blocks = di.in_category(Block)
-        except:
-            if(tries < 3):
-                # May not be built just yet; sleep and try again
-                sys.stderr.write("XML parsing problem with file {0}, retrying.\n".format(
-                        swigdocfilename))
-                time.sleep(1)
-                tries += 1
-            else:
-                # if we've given it three tries, give up and raise an error
-                sys.stderr.write("XML parsing error with file {0}. giving up.\n".format(
-                        swigdocfilename))
-                raise
-        else:
-            break
+    blocks = di.in_category(Block)
+    blocks2 = di.in_category(Block2)
 
     make_funcs = set([])
     for block in blocks:
-        tries = 0
-        while(1):
-            try:
-                make_func = di.get_member(make_name(block.name()), DoxyFunction)
+        try:
+            make_func = di.get_member(make_name(block.name()), DoxyFunction)
+            # Don't want to risk writing to output twice.
+            if make_func.name() not in make_funcs:
                 make_funcs.add(make_func.name())
                 output.append(make_block_entry(di, block))
-            except block.ParsingError:
-                sys.stderr.write('Parsing error for block {0}'.format(block.name()))
-            except:
-                if(tries < 3):
-                    # May not be built just yet; sleep and try again
-                    sys.stderr.write("XML parsing problem with file {0}, retrying.\n".format(
-                            swigdocfilename))
-                    time.sleep(1)
-                    tries += 1
-                else:
-                    # if we've given it three tries, give up and raise an error
-                    sys.stderr.write("XML parsing error with file {0}. giving up.\n".format(
-                            swigdocfilename))
-                    raise
-            else:
-                break
+        except block.ParsingError:
+            sys.stderr.write('Parsing error for block {0}\n'.format(block.name()))
+            raise
+
+    for block in blocks2:
+        try:
+            make_func = block.get_member('make', DoxyFunction)
+            make_func_name = block.name() +'::make'
+            # Don't want to risk writing to output twice.
+            if make_func_name not in make_funcs:
+                make_funcs.add(make_func_name)
+                output.append(make_block2_entry(di, block))
+        except block.ParsingError:
+            sys.stderr.write('Parsing error for block {0}\n'.format(block.name()))
+            raise
 
     # Create docstrings for functions
     # Don't include the make functions since they have already been dealt with.
-    funcs = [f for f in di.in_category(DoxyFunction) if f.name() not in make_funcs]
+    funcs = [f for f in di.in_category(DoxyFunction) 
+             if f.name() not in make_funcs and not f.name().startswith('std::')]
     for f in funcs:
         try:
             output.append(make_func_entry(f))
         except f.ParsingError:
-            sys.stderr.write('Parsing error for function {0}'.format(f.name()))
+            sys.stderr.write('Parsing error for function {0}\n'.format(f.name()))
 
     # Create docstrings for classes
     block_names = [block.name() for block in blocks]
-    klasses = [k for k in di.in_category(DoxyClass) if k.name() not in block_names]
+    block_names += [block.name() for block in blocks2]
+    klasses = [k for k in di.in_category(DoxyClass)
+               if k.name() not in block_names and not k.name().startswith('std::')]
     for k in klasses:
         try:
             output.append(make_class_entry(k))
         except k.ParsingError:
-            sys.stderr.write('Parsing error for class {0}'.format(k.name()))
+            sys.stderr.write('Parsing error for class {0}\n'.format(k.name()))
 
     # Docstrings are not created for anything that is not a function or a class.
     # If this excludes anything important please add it here.
@@ -286,24 +323,4 @@ if __name__ == "__main__":
     custom_output = "\n\n".join(output)
 
     # Generate the docstrings interface file.
-    # If parsing error on NoSuchMember, try again by rereading everything.
-    # Give up after 3 tries.
-    tries = 0
-    while(1):
-        try:
-            make_swig_interface_file(di, swigdocfilename, custom_output=custom_output)
-        except:
-            if(tries < 3):
-                # May not be built just yet; sleep and try again
-                sys.stderr.write("XML parsing problem with file {0}, retrying.\n".format(
-                        swigdocfilename))
-                time.sleep(1)
-                tries += 1
-            else:
-                # if we've given it three tries, give up and raise an error
-                sys.stderr.write("XML parsing error with file {0}. giving up.\n".format(
-                        swigdocfilename))
-                raise
-        else:
-            break
-
+    make_swig_interface_file(di, swigdocfilename, custom_output=custom_output)
author	Tom Rondeau <trondeau@vt.edu>	2012-09-06 12:01:23 -0400
committer	Tom Rondeau <trondeau@vt.edu>	2012-09-06 12:01:23 -0400
commit	c9dc582402d2551ead29a60256fdf64a1d43534c (patch)
tree	4e9fe56c173a8e080c84c4c113a5ac5c5f1c236c /docs/doxygen
parent	1300d48af4752037feac4fae7c3c64187cc0a5a8 (diff)
parent	a4e2e8a9a2c8a6bbd6d676a17b0e2732e11af09f (diff)