text: #!/usr/bin/env python3
  #
  #  Syntax: mkdoc.py [-I<path> ..] [.. a list of header files ..]
  #
  #  Extract documentation from C++ header files to use it in Python bindings
  #
  
  import os
  import sys
  import platform
  import re
  import textwrap
  
  from clang import cindex
  from clang.cindex import CursorKind
  from collections import OrderedDict
  from threading import Thread, Semaphore
  from multiprocessing import cpu_count
  
  RECURSE_LIST = [
      CursorKind.TRANSLATION_UNIT,
      CursorKind.NAMESPACE,
      CursorKind.CLASS_DECL,
      CursorKind.STRUCT_DECL,
      CursorKind.ENUM_DECL,
      CursorKind.CLASS_TEMPLATE
  ]
  
  PRINT_LIST = [
      CursorKind.CLASS_DECL,
      CursorKind.STRUCT_DECL,
      CursorKind.ENUM_DECL,
      CursorKind.ENUM_CONSTANT_DECL,
      CursorKind.CLASS_TEMPLATE,
      CursorKind.FUNCTION_DECL,
      CursorKind.FUNCTION_TEMPLATE,
      CursorKind.CONVERSION_FUNCTION,
      CursorKind.CXX_METHOD,
      CursorKind.CONSTRUCTOR,
      CursorKind.FIELD_DECL
  ]
  
  CPP_OPERATORS = {
      '<=': 'le', '>=': 'ge', '==': 'eq', '!=': 'ne', '[]': 'array',
      '+=': 'iadd', '-=': 'isub', '*=': 'imul', '/=': 'idiv', '%=':
      'imod', '&=': 'iand', '|=': 'ior', '^=': 'ixor', '<<=': 'ilshift',
      '>>=': 'irshift', '++': 'inc', '--': 'dec', '<<': 'lshift', '>>':
      'rshift', '&&': 'land', '||': 'lor', '!': 'lnot', '~': 'bnot',
      '&': 'band', '|': 'bor', '+': 'add', '-': 'sub', '*': 'mul', '/':
      'div', '%': 'mod', '<': 'lt', '>': 'gt', '=': 'assign', '()': 'call'
  }
  
  CPP_OPERATORS = OrderedDict(
      sorted(CPP_OPERATORS.items(), key=lambda t: -len(t[0])))
  
  job_count = cpu_count()
  job_semaphore = Semaphore(job_count)
  
  registered_names = dict()
  
  
  def d(s):
      return s.decode('utf8')
  
  
  def sanitize_name(name):
      global registered_names
      name = re.sub(r'type-parameter-0-([0-9]+)', r'T\1', name)
      for k, v in CPP_OPERATORS.items():
          name = name.replace('operator%s' % k, 'operator_%s' % v)
      name = re.sub('<.*>', '', name)
      name = ''.join([ch if ch.isalnum() else '_' for ch in name])
      name = re.sub('_$', '', re.sub('_+', '_', name))
      if name in registered_names:
          registered_names[name] += 1
          name += '_' + str(registered_names[name])
      else:
          registered_names[name] = 1
      return '__doc_' + name
  
  
  def process_comment(comment):
      result = ''
  
      # Remove C++ comment syntax
      leading_spaces = float('inf')
      for s in comment.expandtabs(tabsize=4).splitlines():
          s = s.strip()
          if s.startswith('/*'):
              s = s[2:].lstrip('*')
          elif s.endswith('*/'):
              s = s[:-2].rstrip('*')
          elif s.startswith('///'):
              s = s[3:]
          if s.startswith('*'):
              s = s[1:]
          if len(s) > 0:
              leading_spaces = min(leading_spaces, len(s) - len(s.lstrip()))
          result += s + '\n'
  
      if leading_spaces != float('inf'):
          result2 = ""
          for s in result.splitlines():
              result2 += s[leading_spaces:] + '\n'
          result = result2
  
      # Doxygen tags
      cpp_group = '([\w:]+)'
      param_group = '([\[\w:\]]+)'
  
      s = result
      s = re.sub(r'\\c\s+%s' % cpp_group, r'``\1``', s)
      s = re.sub(r'\\a\s+%s' % cpp_group, r'*\1*', s)
      s = re.sub(r'\\e\s+%s' % cpp_group, r'*\1*', s)
      s = re.sub(r'\\em\s+%s' % cpp_group, r'*\1*', s)
      s = re.sub(r'\\b\s+%s' % cpp_group, r'**\1**', s)
      s = re.sub(r'\\ingroup\s+%s' % cpp_group, r'', s)
      s = re.sub(r'\\param%s?\s+%s' % (param_group, cpp_group),
                 r'\n\n$Parameter ``\2``:\n\n', s)
      s = re.sub(r'\\tparam%s?\s+%s' % (param_group, cpp_group),
                 r'\n\n$Template parameter ``\2``:\n\n', s)
  
      for in_, out_ in {
          'return': 'Returns',
          'author': 'Author',
          'authors': 'Authors',
          'copyright': 'Copyright',
          'date': 'Date',
          'remark': 'Remark',
          'sa': 'See also',
          'see': 'See also',
          'extends': 'Extends',
          'throw': 'Throws',
          'throws': 'Throws'
      }.items():
          s = re.sub(r'\\%s\s*' % in_, r'\n\n$%s:\n\n' % out_, s)
  
      s = re.sub(r'\\details\s*', r'\n\n', s)
      s = re.sub(r'\\brief\s*', r'', s)
      s = re.sub(r'\\short\s*', r'', s)
      s = re.sub(r'\\ref\s*', r'', s)
  
      s = re.sub(r'\\code\s?(.*?)\s?\\endcode',
                 r"```\n\1\n```\n", s, flags=re.DOTALL)
  
      # HTML/TeX tags
      s = re.sub(r'<tt>(.*?)</tt>', r'``\1``', s, flags=re.DOTALL)
      s = re.sub(r'<pre>(.*?)</pre>', r"```\n\1\n```\n", s, flags=re.DOTALL)
      s = re.sub(r'<em>(.*?)</em>', r'*\1*', s, flags=re.DOTALL)
      s = re.sub(r'<b>(.*?)</b>', r'**\1**', s, flags=re.DOTALL)
      s = re.sub(r'\\f\$(.*?)\\f\$', r'$\1$', s, flags=re.DOTALL)
      s = re.sub(r'<li>', r'\n\n* ', s)
      s = re.sub(r'</?ul>', r'', s)
      s = re.sub(r'</li>', r'\n\n', s)
  
      s = s.replace('``true``', '``True``')
      s = s.replace('``false``', '``False``')
  
      # Re-flow text
      wrapper = textwrap.TextWrapper()
      wrapper.expand_tabs = True
      wrapper.replace_whitespace = True
      wrapper.drop_whitespace = True
      wrapper.width = 70
      wrapper.initial_indent = wrapper.subsequent_indent = ''
  
      result = ''
      in_code_segment = False
      for x in re.split(r'(```)', s):
          if x == '```':
              if not in_code_segment:
                  result += '```\n'
              else:
                  result += '\n```\n\n'
              in_code_segment = not in_code_segment
          elif in_code_segment:
              result += x.strip()
          else:
              for y in re.split(r'(?: *\n *){2,}', x):
                  wrapped = wrapper.fill(re.sub(r'\s+', ' ', y).strip())
                  if len(wrapped) > 0 and wrapped[0] == '$':
                      result += wrapped[1:] + '\n'
                      wrapper.initial_indent = \
                          wrapper.subsequent_indent = ' ' * 4
                  else:
                      if len(wrapped) > 0:
                          result += wrapped + '\n\n'
                      wrapper.initial_indent = wrapper.subsequent_indent = ''
      return result.rstrip().lstrip('\n')
  
  
  def extract(filename, node, prefix, output):
      num_extracted = 0
      if not (node.location.file is None or
              os.path.samefile(d(node.location.file.name), filename)):
          return 0
      if node.kind in RECURSE_LIST:
          sub_prefix = prefix
          if node.kind != CursorKind.TRANSLATION_UNIT:
              if len(sub_prefix) > 0:
                  sub_prefix += '_'
              sub_prefix += d(node.spelling)
          for i in node.get_children():
              num_extracted += extract(filename, i, sub_prefix, output)
          if num_extracted == 0:
              return 0
      if node.kind in PRINT_LIST:
          comment = d(node.raw_comment) if node.raw_comment is not None else ''
          comment = process_comment(comment)
          sub_prefix = prefix
          if len(sub_prefix) > 0:
              sub_prefix += '_'
          if len(node.spelling) > 0:
              name = sanitize_name(sub_prefix + d(node.spelling))
              output.append('\nstatic const char *%s =%sR"doc(%s)doc";' %
                  (name, '\n' if '\n' in comment else ' ', comment))
              num_extracted += 1
      return num_extracted
  
  
  class ExtractionThread(Thread):
      def __init__(self, filename, parameters, output):
          Thread.__init__(self)
          self.filename = filename
          self.parameters = parameters
          self.output = output
          job_semaphore.acquire()
  
      def run(self):
          print('Processing "%s" ..' % self.filename, file=sys.stderr)
          try:
              index = cindex.Index(
                  cindex.conf.lib.clang_createIndex(False, True))
              tu = index.parse(self.filename, self.parameters)
              extract(self.filename, tu.cursor, '', self.output)
          finally:
              job_semaphore.release()
  
  if __name__ == '__main__':
      parameters = ['-x', 'c++', '-std=c++11']
      filenames = []
  
      if platform.system() == 'Darwin':
          dev_path = '/Applications/Xcode.app/Contents/Developer/'
          lib_dir = dev_path + 'Toolchains/XcodeDefault.xctoolchain/usr/lib/'
          sdk_dir = dev_path + 'Platforms/MacOSX.platform/Developer/SDKs'
          libclang = lib_dir + 'libclang.dylib'
  
          if os.path.exists(libclang):
              cindex.Config.set_library_path(os.path.dirname(libclang))
  
          if os.path.exists(sdk_dir):
              sysroot_dir = os.path.join(sdk_dir, next(os.walk(sdk_dir))[1][0])
              parameters.append('-isysroot')
              parameters.append(sysroot_dir)
  
      for item in sys.argv[1:]:
          if item.startswith('-'):
              parameters.append(item)
          else:
              filenames.append(item)
  
      if len(filenames) == 0:
          print('Syntax: %s [.. a list of header files ..]' % sys.argv[0])
          exit(-1)
  
      print('''/*
    This file contains docstrings for the Python bindings.
    Do not edit! These were automatically extracted by mkdoc.py
   */
  
  #define __EXPAND(x)                                      x
  #define __COUNT(_1, _2, _3, _4, _5, _6, _7, COUNT, ...)  COUNT
  #define __VA_SIZE(...)                                   __EXPAND(__COUNT(__VA_ARGS__, 7, 6, 5, 4, 3, 2, 1))
  #define __CAT1(a, b)                                     a ## b
  #define __CAT2(a, b)                                     __CAT1(a, b)
  #define __DOC1(n1)                                       __doc_##n1
  #define __DOC2(n1, n2)                                   __doc_##n1##_##n2
  #define __DOC3(n1, n2, n3)                               __doc_##n1##_##n2##_##n3
  #define __DOC4(n1, n2, n3, n4)                           __doc_##n1##_##n2##_##n3##_##n4
  #define __DOC5(n1, n2, n3, n4, n5)                       __doc_##n1##_##n2##_##n3##_##n4##_##n5
  #define __DOC6(n1, n2, n3, n4, n5, n6)                   __doc_##n1##_##n2##_##n3##_##n4##_##n5##_##n6
  #define __DOC7(n1, n2, n3, n4, n5, n6, n7)               __doc_##n1##_##n2##_##n3##_##n4##_##n5##_##n6##_##n7
  #define DOC(...)                                         __EXPAND(__EXPAND(__CAT2(__DOC, __VA_SIZE(__VA_ARGS__)))(__VA_ARGS__))
  
  #if defined(__GNUG__)
  #pragma GCC diagnostic push
  #pragma GCC diagnostic ignored "-Wunused-variable"
  #endif
  ''')
  
      output = []
      for filename in filenames:
          thr = ExtractionThread(filename, parameters, output)
          thr.start()
  
      print('Waiting for jobs to finish ..', file=sys.stderr)
      for i in range(job_count):
          job_semaphore.acquire()
  
      output.sort()
      for l in output:
          print(l)
  
      print('''
  #if defined(__GNUG__)
  #pragma GCC diagnostic pop
  #endif
  ''')
  