2 Copyright 2008, 2009 Free Software Foundation, Inc.
3 This file is part of GNU Radio
5 GNU Radio Companion is free software; you can redistribute it and/or
6 modify it under the terms of the GNU General Public License
7 as published by the Free Software Foundation; either version 2
8 of the License, or (at your option) any later version.
10 GNU Radio Companion is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 GNU General Public License for more details.
15 You should have received a copy of the GNU General Public License
16 along with this program; if not, write to the Free Software
17 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
20 from Constants import DOCS_DIR
21 from lxml import etree
25 DOXYGEN_NAME_XPATH = '/doxygen/compounddef/compoundname'
26 DOXYGEN_BRIEFDESC_GR_XPATH = '/doxygen/compounddef/briefdescription'
27 DOXYGEN_DETAILDESC_GR_XPATH = '/doxygen/compounddef/detaileddescription'
31 Recursivly pull the text out of an xml tree.
32 @param xml the xml tree
35 text = (xml.text or '').replace('\n', '')
36 tail = (xml.tail or '').replace('\n', '')
37 if xml.tag == 'para': tail += '\n\n'
38 if xml.tag == 'linebreak': text += '\n'
39 if xml.tag == 'parametername': text += ': '
40 return text + ''.join(
41 map(lambda x: extract_txt(x), xml)
46 Extract the documentation from the doxygen generated xml files.
47 If multiple files match, combine the docs.
48 @param key the block key
49 @return a string with documentation
51 docs_dir = os.path.join(DOCS_DIR, 'xml')
52 if not os.path.exists(docs_dir): return ''
54 pattern = key.replace('_', '_*').replace('x', '\w')
55 class_file_matcher = re.compile('^class%s\..*$'%pattern) #xml or xml.gz
56 matches = filter(lambda f: class_file_matcher.match(f), os.listdir(docs_dir))
61 xml_file = os.path.join(docs_dir, match)
62 xml = etree.parse(xml_file)
64 comp_name = extract_txt(xml.xpath(DOXYGEN_NAME_XPATH)[0]).strip()
65 comp_name = ' --- ' + comp_name + ' --- '
66 if re.match('(gr|usrp2|trellis|noaa)_.*', key):
67 brief_desc = extract_txt(xml.xpath(DOXYGEN_BRIEFDESC_GR_XPATH)[0]).strip()
68 detailed_desc = extract_txt(xml.xpath(DOXYGEN_DETAILDESC_GR_XPATH)[0]).strip()
73 doc_strs.append('\n\n'.join([comp_name, brief_desc, detailed_desc]).strip())
74 except IndexError: pass #bad format
75 return '\n\n'.join(doc_strs)
80 Call the private extract and cache the result.
81 @param key the block key
82 @return a string with documentation
84 try: assert _docs_cache.has_key(key)
85 except: _docs_cache[key] = _extract(key)
86 return _docs_cache[key]
88 if __name__ == '__main__':
90 print extract(sys.argv[1])