docs: def pkg_config(packages, default_libraries, executable='pkg-config'):
      """
      Uses pkg-config to update a set of distutils Extension arguments
      to include the flags necessary to link against the given packages.
  
      If the pkg-config lookup fails, default_libraries is applied to
      libraries.
  
      Parameters
      ----------
      packages : list of str
          A list of pkg-config packages to look up.
  
      default_libraries : list of str
          A list of library names to use if the pkg-config lookup fails.
  
      Returns
      -------
      config : dict
          A dictionary containing keyword arguments to
          `distutils.Extension`.  These entries include:
  
          - ``include_dirs``: A list of include directories
          - ``library_dirs``: A list of library directories
          - ``libraries``: A list of libraries
          - ``define_macros``: A list of macro defines
          - ``undef_macros``: A list of macros to undefine
          - ``extra_compile_args``: A list of extra arguments to pass to
            the compiler
      """
  
      flag_map = {'-I': 'include_dirs', '-L': 'library_dirs', '-l': 'libraries',
                  '-D': 'define_macros', '-U': 'undef_macros'}
      command = "{0} --libs --cflags {1}".format(executable, ' '.join(packages)),
  
      result = DistutilsExtensionArgs()
  
      try:
          pipe = subprocess.Popen(command, shell=True, stdout=subprocess.PIPE)
          output = pipe.communicate()[0].strip()
      except subprocess.CalledProcessError as e:
          lines = [
              ("{0} failed. This may cause the build to fail below."
               .format(executable)),
              "  command: {0}".format(e.cmd),
              "  returncode: {0}".format(e.returncode),
              "  output: {0}".format(e.output)
              ]
          log.warn('\n'.join(lines))
          result['libraries'].extend(default_libraries)
      else:
          if pipe.returncode != 0:
              lines = [
                  "pkg-config could not lookup up package(s) {0}.".format(
                      ", ".join(packages)),
                  "This may cause the build to fail below."
                  ]
              log.warn('\n'.join(lines))
              result['libraries'].extend(default_libraries)
          else:
              for token in output.split():
                  # It's not clear what encoding the output of
                  # pkg-config will come to us in.  It will probably be
                  # some combination of pure ASCII (for the compiler
                  # flags) and the filesystem encoding (for any argument
                  # that includes directories or filenames), but this is
                  # just conjecture, as the pkg-config documentation
                  # doesn't seem to address it.
                  arg = token[:2].decode('ascii')
                  value = token[2:].decode(sys.getfilesystemencoding())
                  if arg in flag_map:
                      if arg == '-D':
                          value = tuple(value.split('=', 1))
                      result[flag_map[arg]].append(value)
                  else:
                      result['extra_compile_args'].append(value)
  
      return result