diff options
Diffstat (limited to 'grc/src/grc_gnuradio/utils/extract_docs.py')
| -rw-r--r-- | grc/src/grc_gnuradio/utils/extract_docs.py | 109 |
1 files changed, 109 insertions, 0 deletions
diff --git a/grc/src/grc_gnuradio/utils/extract_docs.py b/grc/src/grc_gnuradio/utils/extract_docs.py new file mode 100644 index 000000000..bc0dcd446 --- /dev/null +++ b/grc/src/grc_gnuradio/utils/extract_docs.py @@ -0,0 +1,109 @@ +""" +Copyright 2008 Free Software Foundation, Inc. +This file is part of GNU Radio + +GNU Radio Companion 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 2 +of the License, or (at your option) any later version. + +GNU Radio Companion 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 this program; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA +""" +##@package grc_gnuradio.utils.extract_docs +#Extract documentation from the gnuradio doxygen files. +#@author Josh Blum + +from grc_gnuradio.Constants import * +from lxml import etree +import os + +DOXYGEN_NAME_XPATH = '/doxygen/compounddef/compoundname' +DOXYGEN_BRIEFDESC_GR_XPATH = '/doxygen/compounddef/briefdescription' +DOXYGEN_DETAILDESC_GR_XPATH = '/doxygen/compounddef/detaileddescription' +DOXYGEN_BRIEFDESC_BLKS2_XPATH = '/doxygen/compounddef/sectiondef[@kind="public-func"]/memberdef/briefdescription' +DOXYGEN_DETAILDESC_BLKS2_XPATH = '/doxygen/compounddef/sectiondef[@kind="public-func"]/memberdef/detaileddescription' + +def extract_txt(xml): + """! + Recursivly pull the text out of an xml tree. + @param xml the xml tree + @return a string + """ + text = xml.text or '' + if not len(xml): return text + return ''.join([text] + map(extract_txt, xml)) + +def is_match(key, file): + """! + Is the block key a match for the given file name? + @param key block key + @param file the xml file name + @return true if matches + """ + if not file.endswith('.xml'): return False + file = file.replace('.xml', '') #remove file ext + file = file.replace('__', '_') #doxygen xml files have 2 underscores + if key.startswith('gr_'): + if not file.startswith('classgr_'): return False + key = key.replace('gr_', 'classgr_') + elif key.startswith('trellis_'): + if not file.startswith('classtrellis_'): return False + key = key.replace('trellis_', 'classtrellis_') + elif key.startswith('blks2_'): + if not file.startswith('classgnuradio_'): return False + if 'blks2' not in file: return False + file = file.replace('_1_1', '_') #weird blks2 doxygen syntax + key = key.replace('blks2_', '') + else: return False + for k, f in zip(*map(reversed, map(lambda x: x.split('_'), [key, file]))): + if k == f: continue + ks = k.split('x') + if len(ks) == 2 and f.startswith(ks[0]) and f.endswith(ks[1]): continue + if len(ks) > 2 and all(ki in ('x', fi) for ki, fi in zip(k, f)): continue + return False + return True + +def extract(key): + """! + Extract the documentation from the doxygen generated xml files. + If multiple files match, combine the docs. + @param key the block key + @return a string with documentation + """ + #get potential xml file matches for the key + if os.path.exists(DOCS_DIR) and os.path.isdir(DOCS_DIR): + matches = filter(lambda f: is_match(key, f), os.listdir(DOCS_DIR)) + else: matches = list() + #combine all matches + doc_strs = list() + for match in matches: + try: + xml_file = DOCS_DIR + '/' + match + xml = etree.parse(xml_file) + #extract descriptions + comp_name = extract_txt(xml.xpath(DOXYGEN_NAME_XPATH)[0]).strip('\n') + comp_name = ' --- ' + comp_name + ' --- ' + if key.startswith('gr_') or key.startswith('trellis_'): + brief_desc = extract_txt(xml.xpath(DOXYGEN_BRIEFDESC_GR_XPATH)[0]).strip('\n') + detailed_desc = extract_txt(xml.xpath(DOXYGEN_DETAILDESC_GR_XPATH)[0]).strip('\n') + elif key.startswith('blks2_'): + brief_desc = extract_txt(xml.xpath(DOXYGEN_BRIEFDESC_BLKS2_XPATH)[0]).strip('\n') + detailed_desc = extract_txt(xml.xpath(DOXYGEN_DETAILDESC_BLKS2_XPATH)[0]).strip('\n') + else: + brief_desc = '' + detailed_desc = '' + #combine + doc_strs.append('\n'.join([comp_name, brief_desc, detailed_desc]).strip('\n')) + except IndexError: pass #bad format + return '\n\n'.join(doc_strs) + +if __name__ == '__main__': + import sys + print extract(sys.argv[1]) |