docs: Update docs template to the latest from GNURadio
Signed-off-by: Sylvain Munaut <tnt@246tNt.com>
This commit is contained in:
parent
9c2cfbca39
commit
0db42ae287
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
|
@ -1,7 +1,8 @@
|
|||
#
|
||||
# Copyright 2010 Free Software Foundation, Inc.
|
||||
#
|
||||
# This file is part of GNU Radio
|
||||
# This file was generated by gr_modtool, a tool from the GNU Radio framework
|
||||
# This file is a part of gr-iqbalance
|
||||
#
|
||||
# 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
|
||||
|
@ -63,8 +64,9 @@ This line is uninformative and is only to test line breaks in the comments.
|
|||
u'Outputs the vital aadvark statistics.'
|
||||
|
||||
"""
|
||||
from __future__ import unicode_literals
|
||||
|
||||
from doxyindex import DoxyIndex, DoxyFunction, DoxyParam, DoxyClass, DoxyFile, DoxyNamespace, DoxyGroup, DoxyFriend, DoxyOther
|
||||
from .doxyindex import DoxyIndex, DoxyFunction, DoxyParam, DoxyClass, DoxyFile, DoxyNamespace, DoxyGroup, DoxyFriend, DoxyOther
|
||||
|
||||
def _test():
|
||||
import os
|
||||
|
|
|
@ -1,7 +1,8 @@
|
|||
#
|
||||
# Copyright 2010 Free Software Foundation, Inc.
|
||||
#
|
||||
# This file is part of GNU Radio
|
||||
# This file was generated by gr_modtool, a tool from the GNU Radio framework
|
||||
# This file is a part of gr-iqbalance
|
||||
#
|
||||
# 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
|
||||
|
@ -24,24 +25,26 @@ A base class is created.
|
|||
Classes based upon this are used to make more user-friendly interfaces
|
||||
to the doxygen xml docs than the generated classes provide.
|
||||
"""
|
||||
from __future__ import print_function
|
||||
from __future__ import unicode_literals
|
||||
|
||||
import os
|
||||
import pdb
|
||||
|
||||
from xml.parsers.expat import ExpatError
|
||||
|
||||
from generated import compound
|
||||
from .generated import compound
|
||||
|
||||
|
||||
class Base(object):
|
||||
|
||||
class Duplicate(StandardError):
|
||||
class Duplicate(Exception):
|
||||
pass
|
||||
|
||||
class NoSuchMember(StandardError):
|
||||
class NoSuchMember(Exception):
|
||||
pass
|
||||
|
||||
class ParsingError(StandardError):
|
||||
class ParsingError(Exception):
|
||||
pass
|
||||
|
||||
def __init__(self, parse_data, top=None):
|
||||
|
@ -94,7 +97,7 @@ class Base(object):
|
|||
for cls in self.mem_classes:
|
||||
if cls.can_parse(mem):
|
||||
return cls
|
||||
raise StandardError(("Did not find a class for object '%s'." \
|
||||
raise Exception(("Did not find a class for object '%s'." \
|
||||
% (mem.get_name())))
|
||||
|
||||
def convert_mem(self, mem):
|
||||
|
@ -102,11 +105,11 @@ class Base(object):
|
|||
cls = self.get_cls(mem)
|
||||
converted = cls.from_parse_data(mem, self.top)
|
||||
if converted is None:
|
||||
raise StandardError('No class matched this object.')
|
||||
raise Exception('No class matched this object.')
|
||||
self.add_ref(converted)
|
||||
return converted
|
||||
except StandardError, e:
|
||||
print e
|
||||
except Exception as e:
|
||||
print(e)
|
||||
|
||||
@classmethod
|
||||
def includes(cls, inst):
|
||||
|
|
|
@ -1,7 +1,8 @@
|
|||
#
|
||||
# Copyright 2010 Free Software Foundation, Inc.
|
||||
#
|
||||
# This file is part of GNU Radio
|
||||
# This file was generated by gr_modtool, a tool from the GNU Radio framework
|
||||
# This file is a part of gr-iqbalance
|
||||
#
|
||||
# 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
|
||||
|
@ -22,12 +23,14 @@
|
|||
Classes providing more user-friendly interfaces to the doxygen xml
|
||||
docs than the generated classes provide.
|
||||
"""
|
||||
from __future__ import absolute_import
|
||||
from __future__ import unicode_literals
|
||||
|
||||
import os
|
||||
|
||||
from generated import index
|
||||
from base import Base
|
||||
from text import description
|
||||
from .generated import index
|
||||
from .base import Base
|
||||
from .text import description
|
||||
|
||||
class DoxyIndex(Base):
|
||||
"""
|
||||
|
@ -43,13 +46,16 @@ class DoxyIndex(Base):
|
|||
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
|
||||
# from the parent rather than having to go through the file
|
||||
# object.
|
||||
# For files and namespaces we want the contents to be
|
||||
# accessible directly from the parent rather than having
|
||||
# to go through the file object.
|
||||
if self.get_cls(mem) == DoxyFile:
|
||||
if mem.name.endswith('.h'):
|
||||
self._members += converted.members()
|
||||
self._members.append(converted)
|
||||
elif self.get_cls(mem) == DoxyNamespace:
|
||||
self._members += converted.members()
|
||||
self._members.append(converted)
|
||||
else:
|
||||
self._members.append(converted)
|
||||
|
||||
|
@ -80,13 +86,29 @@ class DoxyCompMem(Base):
|
|||
self._data['brief_description'] = bd
|
||||
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
|
||||
|
||||
class DoxyMember(DoxyCompMem):
|
||||
pass
|
||||
|
||||
|
||||
class DoxyFunction(DoxyMember):
|
||||
|
||||
__module__ = "gnuradio.utils.doxyxml"
|
||||
|
@ -98,10 +120,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'])
|
||||
|
@ -121,9 +146,39 @@ 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 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):
|
||||
|
||||
|
@ -139,12 +194,14 @@ 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)
|
||||
|
||||
|
@ -177,6 +234,16 @@ class DoxyNamespace(DoxyCompound):
|
|||
|
||||
kind = 'namespace'
|
||||
|
||||
def _parse(self):
|
||||
if self._parsed:
|
||||
return
|
||||
super(DoxyNamespace, self)._parse()
|
||||
self.retrieve_data()
|
||||
self.set_descriptions(self._retrieved_data.compounddef)
|
||||
if self._error:
|
||||
return
|
||||
self.process_memberdefs()
|
||||
|
||||
Base.mem_classes.append(DoxyNamespace)
|
||||
|
||||
|
||||
|
@ -227,11 +294,11 @@ class DoxyOther(Base):
|
|||
|
||||
__module__ = "gnuradio.utils.doxyxml"
|
||||
|
||||
kinds = set(['variable', 'struct', 'union', 'define', 'typedef', 'enum', 'dir', 'page'])
|
||||
kinds = set(['variable', 'struct', 'union', 'define', 'typedef', 'enum',
|
||||
'dir', 'page', 'signal', 'slot', 'property'])
|
||||
|
||||
@classmethod
|
||||
def can_parse(cls, obj):
|
||||
return obj.kind in cls.kinds
|
||||
|
||||
Base.mem_classes.append(DoxyOther)
|
||||
|
||||
|
|
|
@ -5,3 +5,4 @@ These do the real work of parsing the doxygen xml files but the
|
|||
resultant classes are not very friendly to navigate so the rest of the
|
||||
doxyxml module processes them further.
|
||||
"""
|
||||
from __future__ import unicode_literals
|
||||
|
|
|
@ -3,15 +3,17 @@
|
|||
"""
|
||||
Generated Mon Feb 9 19:08:05 2009 by generateDS.py.
|
||||
"""
|
||||
from __future__ import absolute_import
|
||||
from __future__ import unicode_literals
|
||||
|
||||
|
||||
from string import lower as str_lower
|
||||
from xml.dom import minidom
|
||||
from xml.dom import Node
|
||||
|
||||
import sys
|
||||
|
||||
import compoundsuper as supermod
|
||||
from compoundsuper import MixedContainer
|
||||
from . import compoundsuper as supermod
|
||||
from .compoundsuper import MixedContainer
|
||||
|
||||
|
||||
class DoxygenTypeSub(supermod.DoxygenType):
|
||||
|
|
|
@ -4,12 +4,17 @@
|
|||
# Generated Thu Jun 11 18:44:25 2009 by generateDS.py.
|
||||
#
|
||||
|
||||
from __future__ import print_function
|
||||
from __future__ import unicode_literals
|
||||
|
||||
import sys
|
||||
import getopt
|
||||
from string import lower as str_lower
|
||||
|
||||
from xml.dom import minidom
|
||||
from xml.dom import Node
|
||||
|
||||
import six
|
||||
|
||||
|
||||
#
|
||||
# User methods
|
||||
#
|
||||
|
@ -19,9 +24,9 @@ from xml.dom import Node
|
|||
|
||||
try:
|
||||
from generatedssuper import GeneratedsSuper
|
||||
except ImportError, exp:
|
||||
except ImportError as exp:
|
||||
|
||||
class GeneratedsSuper:
|
||||
class GeneratedsSuper(object):
|
||||
def format_string(self, input_data, input_name=''):
|
||||
return input_data
|
||||
def format_integer(self, input_data, input_name=''):
|
||||
|
@ -64,7 +69,7 @@ def showIndent(outfile, level):
|
|||
outfile.write(' ')
|
||||
|
||||
def quote_xml(inStr):
|
||||
s1 = (isinstance(inStr, basestring) and inStr or
|
||||
s1 = (isinstance(inStr, six.string_types) and inStr or
|
||||
'%s' % inStr)
|
||||
s1 = s1.replace('&', '&')
|
||||
s1 = s1.replace('<', '<')
|
||||
|
@ -72,7 +77,7 @@ def quote_xml(inStr):
|
|||
return s1
|
||||
|
||||
def quote_attrib(inStr):
|
||||
s1 = (isinstance(inStr, basestring) and inStr or
|
||||
s1 = (isinstance(inStr, six.string_types) and inStr or
|
||||
'%s' % inStr)
|
||||
s1 = s1.replace('&', '&')
|
||||
s1 = s1.replace('<', '<')
|
||||
|
@ -102,7 +107,7 @@ def quote_python(inStr):
|
|||
return '"""%s"""' % s1
|
||||
|
||||
|
||||
class MixedContainer:
|
||||
class MixedContainer(object):
|
||||
# Constants for category:
|
||||
CategoryNone = 0
|
||||
CategoryText = 1
|
||||
|
@ -4221,7 +4226,7 @@ class codelineType(GeneratedsSuper):
|
|||
if attrs.get('lineno'):
|
||||
try:
|
||||
self.lineno = int(attrs.get('lineno').value)
|
||||
except ValueError, exp:
|
||||
except ValueError as exp:
|
||||
raise ValueError('Bad integer attribute (lineno): %s' % exp)
|
||||
if attrs.get('refkind'):
|
||||
self.refkind = attrs.get('refkind').value
|
||||
|
@ -4504,12 +4509,12 @@ class referenceType(GeneratedsSuper):
|
|||
if attrs.get('endline'):
|
||||
try:
|
||||
self.endline = int(attrs.get('endline').value)
|
||||
except ValueError, exp:
|
||||
except ValueError as exp:
|
||||
raise ValueError('Bad integer attribute (endline): %s' % exp)
|
||||
if attrs.get('startline'):
|
||||
try:
|
||||
self.startline = int(attrs.get('startline').value)
|
||||
except ValueError, exp:
|
||||
except ValueError as exp:
|
||||
raise ValueError('Bad integer attribute (startline): %s' % exp)
|
||||
if attrs.get('refid'):
|
||||
self.refid = attrs.get('refid').value
|
||||
|
@ -4627,17 +4632,17 @@ class locationType(GeneratedsSuper):
|
|||
if attrs.get('bodystart'):
|
||||
try:
|
||||
self.bodystart = int(attrs.get('bodystart').value)
|
||||
except ValueError, exp:
|
||||
except ValueError as exp:
|
||||
raise ValueError('Bad integer attribute (bodystart): %s' % exp)
|
||||
if attrs.get('line'):
|
||||
try:
|
||||
self.line = int(attrs.get('line').value)
|
||||
except ValueError, exp:
|
||||
except ValueError as exp:
|
||||
raise ValueError('Bad integer attribute (line): %s' % exp)
|
||||
if attrs.get('bodyend'):
|
||||
try:
|
||||
self.bodyend = int(attrs.get('bodyend').value)
|
||||
except ValueError, exp:
|
||||
except ValueError as exp:
|
||||
raise ValueError('Bad integer attribute (bodyend): %s' % exp)
|
||||
if attrs.get('bodyfile'):
|
||||
self.bodyfile = attrs.get('bodyfile').value
|
||||
|
@ -6778,12 +6783,12 @@ class docTableType(GeneratedsSuper):
|
|||
if attrs.get('rows'):
|
||||
try:
|
||||
self.rows = int(attrs.get('rows').value)
|
||||
except ValueError, exp:
|
||||
except ValueError as exp:
|
||||
raise ValueError('Bad integer attribute (rows): %s' % exp)
|
||||
if attrs.get('cols'):
|
||||
try:
|
||||
self.cols = int(attrs.get('cols').value)
|
||||
except ValueError, exp:
|
||||
except ValueError as exp:
|
||||
raise ValueError('Bad integer attribute (cols): %s' % exp)
|
||||
def buildChildren(self, child_, nodeName_):
|
||||
if child_.nodeType == Node.ELEMENT_NODE and \
|
||||
|
@ -7108,7 +7113,7 @@ class docHeadingType(GeneratedsSuper):
|
|||
if attrs.get('level'):
|
||||
try:
|
||||
self.level = int(attrs.get('level').value)
|
||||
except ValueError, exp:
|
||||
except ValueError as exp:
|
||||
raise ValueError('Bad integer attribute (level): %s' % exp)
|
||||
def buildChildren(self, child_, nodeName_):
|
||||
if child_.nodeType == Node.TEXT_NODE:
|
||||
|
@ -8283,7 +8288,7 @@ Options:
|
|||
"""
|
||||
|
||||
def usage():
|
||||
print USAGE_TEXT
|
||||
print(USAGE_TEXT)
|
||||
sys.exit(1)
|
||||
|
||||
|
||||
|
@ -8339,4 +8344,3 @@ if __name__ == '__main__':
|
|||
main()
|
||||
#import pdb
|
||||
#pdb.run('main()')
|
||||
|
||||
|
|
|
@ -3,14 +3,16 @@
|
|||
"""
|
||||
Generated Mon Feb 9 19:08:05 2009 by generateDS.py.
|
||||
"""
|
||||
from __future__ import absolute_import
|
||||
from __future__ import unicode_literals
|
||||
|
||||
from xml.dom import minidom
|
||||
|
||||
import os
|
||||
import sys
|
||||
import compound
|
||||
from . import compound
|
||||
|
||||
import indexsuper as supermod
|
||||
from . import indexsuper as supermod
|
||||
|
||||
class DoxygenTypeSub(supermod.DoxygenType):
|
||||
def __init__(self, version=None, compound=None):
|
||||
|
|
|
@ -4,12 +4,16 @@
|
|||
# Generated Thu Jun 11 18:43:54 2009 by generateDS.py.
|
||||
#
|
||||
|
||||
from __future__ import print_function
|
||||
from __future__ import unicode_literals
|
||||
|
||||
import sys
|
||||
import getopt
|
||||
from string import lower as str_lower
|
||||
|
||||
from xml.dom import minidom
|
||||
from xml.dom import Node
|
||||
|
||||
import six
|
||||
|
||||
#
|
||||
# User methods
|
||||
#
|
||||
|
@ -19,9 +23,9 @@ from xml.dom import Node
|
|||
|
||||
try:
|
||||
from generatedssuper import GeneratedsSuper
|
||||
except ImportError, exp:
|
||||
except ImportError as exp:
|
||||
|
||||
class GeneratedsSuper:
|
||||
class GeneratedsSuper(object):
|
||||
def format_string(self, input_data, input_name=''):
|
||||
return input_data
|
||||
def format_integer(self, input_data, input_name=''):
|
||||
|
@ -64,7 +68,7 @@ def showIndent(outfile, level):
|
|||
outfile.write(' ')
|
||||
|
||||
def quote_xml(inStr):
|
||||
s1 = (isinstance(inStr, basestring) and inStr or
|
||||
s1 = (isinstance(inStr, six.string_types) and inStr or
|
||||
'%s' % inStr)
|
||||
s1 = s1.replace('&', '&')
|
||||
s1 = s1.replace('<', '<')
|
||||
|
@ -72,7 +76,7 @@ def quote_xml(inStr):
|
|||
return s1
|
||||
|
||||
def quote_attrib(inStr):
|
||||
s1 = (isinstance(inStr, basestring) and inStr or
|
||||
s1 = (isinstance(inStr, six.string_types) and inStr or
|
||||
'%s' % inStr)
|
||||
s1 = s1.replace('&', '&')
|
||||
s1 = s1.replace('<', '<')
|
||||
|
@ -102,7 +106,7 @@ def quote_python(inStr):
|
|||
return '"""%s"""' % s1
|
||||
|
||||
|
||||
class MixedContainer:
|
||||
class MixedContainer(object):
|
||||
# Constants for category:
|
||||
CategoryNone = 0
|
||||
CategoryText = 1
|
||||
|
@ -462,7 +466,7 @@ Options:
|
|||
"""
|
||||
|
||||
def usage():
|
||||
print USAGE_TEXT
|
||||
print(USAGE_TEXT)
|
||||
sys.exit(1)
|
||||
|
||||
|
||||
|
@ -520,4 +524,3 @@ if __name__ == '__main__':
|
|||
main()
|
||||
#import pdb
|
||||
#pdb.run('main()')
|
||||
|
||||
|
|
|
@ -1,7 +1,8 @@
|
|||
#
|
||||
# Copyright 2010 Free Software Foundation, Inc.
|
||||
#
|
||||
# This file is part of GNU Radio
|
||||
# This file was generated by gr_modtool, a tool from the GNU Radio framework
|
||||
# This file is a part of gr-iqbalance
|
||||
#
|
||||
# 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
|
||||
|
@ -21,12 +22,13 @@
|
|||
"""
|
||||
Utilities for extracting text from generated classes.
|
||||
"""
|
||||
from __future__ import unicode_literals
|
||||
|
||||
def is_string(txt):
|
||||
if isinstance(txt, str):
|
||||
return True
|
||||
try:
|
||||
if isinstance(txt, unicode):
|
||||
if isinstance(txt, str):
|
||||
return True
|
||||
except NameError:
|
||||
pass
|
||||
|
@ -49,7 +51,7 @@ def description_bit(obj):
|
|||
elif is_string(obj):
|
||||
return obj
|
||||
else:
|
||||
raise StandardError('Expecting a string or something with content, content_ or value attribute')
|
||||
raise Exception('Expecting a string or something with content, content_ or value attribute')
|
||||
# If this bit is a paragraph then add one some line breaks.
|
||||
if hasattr(obj, 'name') and obj.name == 'para':
|
||||
result += "\n\n"
|
||||
|
|
|
@ -1,6 +1,6 @@
|
|||
/*!
|
||||
* \defgroup block GNU Radio IQBALANCE C++ Signal Processing Blocks
|
||||
* \brief All C++ blocks that can be used from the IQBALANCE GNU Radio
|
||||
* \defgroup block GNU Radio TEST C++ Signal Processing Blocks
|
||||
* \brief All C++ blocks that can be used from the TEST GNU Radio
|
||||
* module are listed here or in the subcategories below.
|
||||
*
|
||||
*/
|
||||
|
|
|
@ -1,8 +1,8 @@
|
|||
/*! \mainpage
|
||||
|
||||
Welcome to the GNU Radio IQBALANCE Block
|
||||
Welcome to the GNU Radio TEST Block
|
||||
|
||||
This is the intro page for the Doxygen manual generated for the IQBALANCE
|
||||
This is the intro page for the Doxygen manual generated for the TEST
|
||||
block (docs/doxygen/other/main_page.dox). Edit it to add more detailed
|
||||
documentation about the new GNU Radio modules contained in this
|
||||
project.
|
||||
|
|
|
@ -1,7 +1,8 @@
|
|||
#
|
||||
# Copyright 2010,2011 Free Software Foundation, Inc.
|
||||
# Copyright 2010-2012 Free Software Foundation, Inc.
|
||||
#
|
||||
# This file is part of GNU Radio
|
||||
# This file was generated by gr_modtool, a tool from the GNU Radio framework
|
||||
# This file is a part of gr-iqbalance
|
||||
#
|
||||
# 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
|
||||
|
@ -26,14 +27,12 @@ The file instructs SWIG to transfer the doxygen comments into the
|
|||
python docstrings.
|
||||
|
||||
"""
|
||||
from __future__ import unicode_literals
|
||||
|
||||
import sys
|
||||
|
||||
try:
|
||||
from doxyxml import DoxyIndex, DoxyClass, DoxyFriend, DoxyFunction, DoxyFile, base
|
||||
except ImportError:
|
||||
from gnuradio.doxyxml import DoxyIndex, DoxyClass, DoxyFriend, DoxyFunction, DoxyFile, base
|
||||
import sys, time
|
||||
|
||||
from doxyxml import DoxyIndex, DoxyClass, DoxyFriend, DoxyFunction, DoxyFile
|
||||
from doxyxml import DoxyOther, base
|
||||
|
||||
def py_name(name):
|
||||
bits = name.split('_')
|
||||
|
@ -56,18 +55,41 @@ 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):
|
||||
"""
|
||||
Convert unicode text into ascii and escape quotes.
|
||||
Convert unicode text into ascii and escape quotes and backslashes.
|
||||
"""
|
||||
if text is None:
|
||||
return ''
|
||||
out = text.encode('ascii', 'replace')
|
||||
out = out.replace('"', '\\"')
|
||||
return out
|
||||
# swig will require us to replace blackslash with 4 backslashes
|
||||
out = out.replace(b'\\', b'\\\\\\\\')
|
||||
out = out.replace(b'"', b'\\"').decode('ascii')
|
||||
return str(out)
|
||||
|
||||
|
||||
def combine_descriptions(obj):
|
||||
|
@ -83,9 +105,15 @@ def combine_descriptions(obj):
|
|||
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.
|
||||
|
||||
|
@ -102,6 +130,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 +152,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)
|
||||
#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):
|
||||
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,11 +210,33 @@ 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.
|
||||
class_description = combine_descriptions(block)
|
||||
make_func = block.get_member('make', DoxyFunction)
|
||||
make_description = combine_descriptions(make_func)
|
||||
description = class_description + "\n\nConstructor Specific Documentation:\n\n" + make_description
|
||||
# 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):
|
||||
|
||||
|
@ -196,39 +253,59 @@ def make_swig_interface_file(di, swigdocfilename, custom_output=None):
|
|||
|
||||
# Create docstrings for the blocks.
|
||||
blocks = di.in_category(Block)
|
||||
blocks2 = di.in_category(Block2)
|
||||
|
||||
make_funcs = set([])
|
||||
for block in blocks:
|
||||
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:
|
||||
print('Parsing error for block %s' % block.name())
|
||||
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:
|
||||
print('Parsing error for function %s' % 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:
|
||||
print('Parsing error for class %s' % 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.
|
||||
|
||||
output = "\n\n".join(output)
|
||||
|
||||
swig_doc = file(swigdocfilename, 'w')
|
||||
swig_doc = open(swigdocfilename, 'w')
|
||||
swig_doc.write(output)
|
||||
swig_doc.close()
|
||||
|
||||
|
@ -236,7 +313,7 @@ if __name__ == "__main__":
|
|||
# Parse command line options and set up doxyxml.
|
||||
err_msg = "Execute using: python swig_doc.py xml_path outputfilename"
|
||||
if len(sys.argv) != 3:
|
||||
raise StandardError(err_msg)
|
||||
raise Exception(err_msg)
|
||||
xml_path = sys.argv[1]
|
||||
swigdocfilename = sys.argv[2]
|
||||
di = DoxyIndex(xml_path)
|
||||
|
|
Loading…
Reference in New Issue