summaryrefslogtreecommitdiff
path: root/docs/doxygen
diff options
context:
space:
mode:
authorTom Rondeau2012-05-20 12:38:46 -0400
committerTom Rondeau2012-05-20 12:38:46 -0400
commit0da7b9c4ecf78ad3e34cd942ff3772b7352becf3 (patch)
tree9494bbb3790ccf1d0d83b8eaa9b34792a87826b0 /docs/doxygen
parent59165ed2ec7d45a7875c003ce4ce713082cf62c8 (diff)
parent40d1539f04b945045352db7329ae83562c32ddf0 (diff)
downloadgnuradio-0da7b9c4ecf78ad3e34cd942ff3772b7352becf3.tar.gz
gnuradio-0da7b9c4ecf78ad3e34cd942ff3772b7352becf3.tar.bz2
gnuradio-0da7b9c4ecf78ad3e34cd942ff3772b7352becf3.zip
Merge branch 'sphinxdocs' of https://github.com/benreynwar/gnuradio into sphinxdocs
Diffstat (limited to 'docs/doxygen')
-rw-r--r--docs/doxygen/doxyxml/doxyindex.py81
-rw-r--r--docs/doxygen/swig_doc.py138
2 files changed, 129 insertions, 90 deletions
diff --git a/docs/doxygen/doxyxml/doxyindex.py b/docs/doxygen/doxyxml/doxyindex.py
index 0132ab86f..84bc7b88c 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,14 +78,14 @@ 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
class DoxyCompound(DoxyCompMem):
pass
class DoxyMember(DoxyCompMem):
pass
-
+
class DoxyFunction(DoxyMember):
@@ -111,7 +111,7 @@ Base.mem_classes.append(DoxyFunction)
class DoxyParam(DoxyMember):
-
+
__module__ = "gnuradio.utils.doxyxml"
def _parse(self):
@@ -125,12 +125,33 @@ class DoxyParam(DoxyMember):
detailed_description = property(lambda self: self.data()['detailed_description'])
declname = 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 +160,40 @@ 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()
+ 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
+
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 +203,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 +211,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 +248,7 @@ class DoxyGroup(DoxyCompound):
self.process_memberdefs()
title = property(lambda self: self.data()['title'])
-
+
Base.mem_classes.append(DoxyGroup)
@@ -224,7 +263,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 +271,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/swig_doc.py b/docs/doxygen/swig_doc.py
index bd35b8efd..414748bba 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,7 @@ 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, base
def py_name(name):
bits = name.split('_')
@@ -56,7 +52,9 @@ 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)
+ return is_a_block
def utoascii(text):
@@ -82,13 +80,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 +106,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,16 +128,17 @@ 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)
+ #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):
@@ -138,7 +146,7 @@ def make_class_entry(klass, description=None):
Create a class docstring for a swig interface file.
"""
output = []
- output.append(make_entry(klass, description=description))
+ output.append(make_entry(klass, description=description, params=klass.params))
for func in klass.in_category(DoxyFunction):
name = klass.name() + '::' + func.name()
output.append(make_func_entry(func, name=name))
@@ -177,16 +185,33 @@ def make_block_entry(di, block):
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 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):
-
+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,46 +220,29 @@ 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))
+ 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
@@ -246,7 +254,7 @@ def make_swig_interface_file(di, swigdocfilename, custom_output=None):
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]
@@ -255,7 +263,7 @@ def make_swig_interface_file(di, swigdocfilename, custom_output=None):
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 +299,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
-
+