diff options
Diffstat (limited to 'docs/doxygen')
| -rw-r--r-- | docs/doxygen/doxyxml/doxyindex.py | 103 | ||||
| -rw-r--r-- | docs/doxygen/other/build_guide.dox | 32 | ||||
| -rw-r--r-- | docs/doxygen/swig_doc.py | 219 |
3 files changed, 230 insertions, 124 deletions
diff --git a/docs/doxygen/doxyxml/doxyindex.py b/docs/doxygen/doxyxml/doxyindex.py index 0132ab86f..304109a8e 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 index 780976d62..629a0f89f 100644 --- a/docs/doxygen/other/build_guide.dox +++ b/docs/doxygen/other/build_guide.dox @@ -19,13 +19,16 @@ 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 -\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/ @@ -39,6 +42,9 @@ about building gr-comedi. \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/ @@ -57,6 +63,10 @@ about building gr-comedi. \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 @@ -146,23 +156,3 @@ 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/swig_doc.py b/docs/doxygen/swig_doc.py index bd35b8efd..927747098 100644 --- a/docs/doxygen/swig_doc.py +++ b/docs/doxygen/swig_doc.py @@ -1,23 +1,23 @@ # # Copyright 2010,2011 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,56 @@ 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): +def wait_if_necessary(tries, swigdocfilename, item=None): + if item is not None: + extra = ', item {0}'.format(item.name()) + else: + extra = '' + if(tries < 3): + # May not be built just yet; sleep and try again + sys.stderr.write("XML parsing problem with file {0}{1}, retrying.\n".format( + swigdocfilename, extra)) + time.sleep(1) + tries += 1 + return tries, True + else: + # if we've given it three tries, give up and raise an error + sys.stderr.write("XML parsing error with file {0}{1}. giving up.\n".format( + swigdocfilename, extra)) + return tries, False +def make_swig_interface_file(di, swigdocfilename, custom_output=None, tries=0): + output = [""" /* * This file was automatically generated using swig_doc.py. - * + * * Any changes to it will be lost next time it is regenerated. */ """] @@ -195,67 +264,71 @@ 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) + blocks2 = di.in_category(Block2) 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)) + tries, try_again = wait_if_necessary(tries, swigdocfilename) + if not try_again: raise else: break - make_funcs = set([]) for block in blocks: - tries = 0 while(1): try: make_func = di.get_member(make_name(block.name()), DoxyFunction) - make_funcs.add(make_func.name()) - output.append(make_block_entry(di, block)) + # 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())) + sys.stderr.write('Parsing error for block {0}\n'.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)) + tries, try_again = wait_if_necessary(tries, swigdocfilename, block) + if not try_again: raise else: break + for block in blocks2: + while(1): + 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())) + except: + tries, try_again = wait_if_necessary(tries, swigdocfilename, block) + if not try_again: + raise + else: + break # 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. @@ -291,19 +364,11 @@ if __name__ == "__main__": tries = 0 while(1): try: - make_swig_interface_file(di, swigdocfilename, custom_output=custom_output) + make_swig_interface_file(di, swigdocfilename, custom_output=custom_output, tries=tries) 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)) + tries, try_again = wait_if_necessary(tries, swigdocfilename) + if not try_again: raise else: break - + |