doc/tools/html_functions.py

   1 from __future__ import print_function
   2 import sys
   3
   4 import logging
   5 import os
   6 import re
   7 from pprint import pprint
   8 import traceback
   9
  10 try:
  11     import bs4
  12     from bs4 import BeautifulSoup
  13 except ImportError:
  14     raise ImportError('Error: '
  15                       'Install BeautifulSoup (bs4) for adding'
  16                       ' Python & Java signatures documentation')
  17
  18 def load_html_file(file_dir):
  19     """ Uses BeautifulSoup to load an html """
  20     with open(file_dir, 'rb') as fp:
  21         data = fp.read()
  22     if os.name == 'nt' or sys.version_info[0] == 3:
  23         data = data.decode(encoding='utf-8', errors='strict')
  24     data = re.sub(r'(\>)([ ]+)', lambda match: match.group(1) + ('!space!' * len(match.group(2))), data)
  25     data = re.sub(r'([ ]+)(\<)', lambda match: ('!space!' * len(match.group(1))) + match.group(2), data)
  26     if os.name == 'nt' or sys.version_info[0] == 3:
  27         data = data.encode('utf-8', 'ignore')
  28     soup = BeautifulSoup(data, 'html.parser')
  29     return soup
  30
  31 def update_html(file, soup):
  32     s = str(soup)
  33     s = s.replace('!space!', ' ')
  34     if os.name == 'nt' or sys.version_info[0] == 3:
  35         s = s.encode('utf-8', 'ignore')
  36     with open(file, 'wb') as f:
  37         f.write(s)
  38
  39
  40 def insert_python_signatures(python_signatures, symbols_dict, filepath):
  41     soup = load_html_file(filepath)
  42     entries = soup.find_all(lambda tag: tag.name == "a" and tag.has_attr('id'))
  43     for e in entries:
  44         anchor = e['id']
  45         if anchor in symbols_dict:
  46             s = symbols_dict[anchor]
  47             logging.info('Process: %r' % s)
  48             if s.type == 'fn' or s.type == 'method':
  49                 process_fn(soup, e, python_signatures[s.cppname], s)
  50             elif s.type == 'const':
  51                 process_const(soup, e, python_signatures[s.cppname], s)
  52             else:
  53                 logging.error('unsupported type: %s' % s);
  54
  55     update_html(filepath, soup)
  56
  57
  58 def process_fn(soup, anchor, python_signature, symbol):
  59     try:
  60         r = anchor.find_next_sibling(class_='memitem').find(class_='memproto').find('table')
  61         insert_python_fn_signature(soup, r, python_signature, symbol)
  62     except:
  63         logging.error("Can't process: %s" % symbol)
  64         traceback.print_exc()
  65         pprint(anchor)
  66
  67
  68 def process_const(soup, anchor, python_signature, symbol):
  69     try:
  70         #pprint(anchor.parent)
  71         description = append(soup.new_tag('div', **{'class' : ['python_language']}),
  72             'Python: ' + python_signature[0]['name'])
  73         old = anchor.find_next_sibling('div', class_='python_language')
  74         if old is None:
  75             anchor.parent.append(description)
  76         else:
  77             old.replace_with(description)
  78         #pprint(anchor.parent)
  79     except:
  80         logging.error("Can't process: %s" % symbol)
  81         traceback.print_exc()
  82         pprint(anchor)
  83
  84
  85 def insert_python_fn_signature(soup, table, variants, symbol):
  86     description = create_python_fn_description(soup, variants)
  87     description['class'] = 'python_language'
  88     soup = insert_or_replace(table, description, 'table', 'python_language')
  89     return soup
  90
  91
  92 def create_python_fn_description(soup, variants):
  93     language = 'Python:'
  94     table = soup.new_tag('table')
  95     heading_row = soup.new_tag('th')
  96     table.append(
  97         append(soup.new_tag('tr'),
  98                append(soup.new_tag('th', colspan=999, style="text-align:left"), language)))
  99     for v in variants:
 100         #logging.debug(v)
 101         add_signature_to_table(soup, table, v, language, type)
 102     #print(table)
 103     return table
 104
 105
 106 def add_signature_to_table(soup, table, signature, language, type):
 107     """ Add a signature to an html table"""
 108     row = soup.new_tag('tr')
 109     row.append(soup.new_tag('td', style='width: 20px;'))
 110
 111     if 'ret' in signature:
 112         row.append(append(soup.new_tag('td'), signature['ret']))
 113         row.append(append(soup.new_tag('td'), '='))
 114     else:
 115         row.append(soup.new_tag('td')) # return values
 116         row.append(soup.new_tag('td')) # '='
 117
 118     row.append(append(soup.new_tag('td'), signature['name'] + '('))
 119     row.append(append(soup.new_tag('td', **{'class': 'paramname'}), signature['arg']))
 120     row.append(append(soup.new_tag('td'), ')'))
 121     table.append(row)
 122
 123
 124 def append(target, obj):
 125     target.append(obj)
 126     return target
 127
 128
 129 def insert_or_replace(element_before, new_element, tag, tag_class):
 130     old = element_before.find_next_sibling(tag, class_=tag_class)
 131     if old is None:
 132         element_before.insert_after(new_element)
 133     else:
 134         old.replace_with(new_element)