git.gag.com Git - debian/gnuradio/blob - grc/src/platforms/python/utils/extract_docs.py

   1 """
   2 Copyright 2008, 2009 Free Software Foundation, Inc.
   3 This file is part of GNU Radio
   4
   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.
   9
  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.
  14
  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
  18 """
  19
  20 from .. Constants import DOCS_DIR
  21 from lxml import etree
  22 import os
  23 import re
  24
  25 DOXYGEN_NAME_XPATH = '/doxygen/compounddef/compoundname'
  26 DOXYGEN_BRIEFDESC_GR_XPATH = '/doxygen/compounddef/briefdescription'
  27 DOXYGEN_DETAILDESC_GR_XPATH = '/doxygen/compounddef/detaileddescription'
  28
  29 def extract_txt(xml):
  30         """
  31         Recursivly pull the text out of an xml tree.
  32         @param xml the xml tree
  33         @return a string
  34         """
  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)
  42         ) + tail
  43
  44 def _extract(key):
  45         """
  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
  50         """
  51         UBUNTU_DOCS_DIR = '/usr/share/doc/gnuradio-doc/xml'
  52         if os.path.exists(DOCS_DIR): docs_dir = DOCS_DIR
  53         elif os.path.exists(UBUNTU_DOCS_DIR): docs_dir = UBUNTU_DOCS_DIR
  54         else: return ''
  55         #extract matches
  56         pattern = key.replace('_', '_*').replace('x', '\w')
  57         prog = re.compile('^class%s\..*$'%pattern)
  58         matches = filter(lambda f: prog.match(f), os.listdir(docs_dir))
  59         #combine all matches
  60         doc_strs = list()
  61         for match in matches:
  62                 try:
  63                         xml_file = os.path.join(docs_dir, match)
  64                         xml = etree.parse(xml_file)
  65                         #extract descriptions
  66                         comp_name = extract_txt(xml.xpath(DOXYGEN_NAME_XPATH)[0]).strip()
  67                         comp_name = '   ---   ' + comp_name + '   ---   '
  68                         if re.match('(gr|usrp2|trellis)_.*', key):
  69                                 brief_desc = extract_txt(xml.xpath(DOXYGEN_BRIEFDESC_GR_XPATH)[0]).strip()
  70                                 detailed_desc = extract_txt(xml.xpath(DOXYGEN_DETAILDESC_GR_XPATH)[0]).strip()
  71                         else:
  72                                 brief_desc = ''
  73                                 detailed_desc = ''
  74                         #combine
  75                         doc_strs.append('\n\n'.join([comp_name, brief_desc, detailed_desc]).strip())
  76                 except IndexError: pass #bad format
  77         return '\n\n'.join(doc_strs)
  78
  79 _docs_cache = dict()
  80 def extract(key):
  81         """
  82         Call the private extract and cache the result.
  83         @param key the block key
  84         @return a string with documentation
  85         """
  86         try: assert _docs_cache.has_key(key)
  87         except: _docs_cache[key] = _extract(key)
  88         return _docs_cache[key]
  89
  90 if __name__ == '__main__':
  91         import sys
  92         print extract(sys.argv[1])