summaryrefslogtreecommitdiff
path: root/Build/source/libs/poppler/poppler-src/gtkdoc.py
diff options
context:
space:
mode:
Diffstat (limited to 'Build/source/libs/poppler/poppler-src/gtkdoc.py')
-rw-r--r--Build/source/libs/poppler/poppler-src/gtkdoc.py447
1 files changed, 0 insertions, 447 deletions
diff --git a/Build/source/libs/poppler/poppler-src/gtkdoc.py b/Build/source/libs/poppler/poppler-src/gtkdoc.py
deleted file mode 100644
index cc73ffc1bc3..00000000000
--- a/Build/source/libs/poppler/poppler-src/gtkdoc.py
+++ /dev/null
@@ -1,447 +0,0 @@
-# Copyright (C) 2011 Igalia S.L.
-#
-# This library is free software; you can redistribute it and/or
-# modify it under the terms of the GNU Lesser General Public
-# License as published by the Free Software Foundation; either
-# version 2 of the License, or (at your option) any later version.
-#
-# This library 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
-# Lesser General Public License for more details.
-#
-# You should have received a copy of the GNU Lesser General Public
-# License along with this library; if not, write to the Free Software
-# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
-
-import errno
-import logging
-import os
-import os.path
-import subprocess
-import sys
-
-PY2 = sys.version_info[0] == 2
-
-class GTKDoc(object):
-
- """Class that controls a gtkdoc run.
-
- Each instance of this class represents one gtkdoc configuration
- and set of documentation. The gtkdoc package is a series of tools
- run consecutively which converts inline C/C++ documentation into
- docbook files and then into HTML. This class is suitable for
- generating documentation or simply verifying correctness.
-
- Keyword arguments:
- output_dir -- The path where gtkdoc output should be placed. Generation
- may overwrite file in this directory. Required.
- module_name -- The name of the documentation module. For libraries this
- is typically the library name. Required if not library path
- is given.
- source_dirs -- A list of paths to directories of source code to be scanned.
- Required if headers is not specified.
- ignored_files -- A list of filenames to ignore in the source directory. It is
- only necessary to provide the basenames of these files.
- Typically it is important to provide an updated list of
- ignored files to prevent warnings about undocumented symbols.
- headers -- A list of paths to headers to be scanned. Required if source_dirs
- is not specified.
- namespace -- The library namespace.
- decorator -- If a decorator is used to unhide certain symbols in header
- files this parameter is required for successful scanning.
- (default '')
- deprecation_guard -- gtkdoc tries to ensure that symbols marked as deprecated
- are encased in this C preprocessor define. This is required
- to avoid gtkdoc warnings. (default '')
- cflags -- This parameter specifies any preprocessor flags necessary for
- building the scanner binary during gtkdoc-scanobj. Typically
- this includes all absolute include paths necessary to resolve
- all header dependencies. (default '')
- ldflags -- This parameter specifies any linker flags necessary for
- building the scanner binary during gtkdoc-scanobj. Typically
- this includes "-lyourlibraryname". (default '')
- library_path -- This parameter specifies the path to the directory where you
- library resides used for building the scanner binary during
- gtkdoc-scanobj. (default '')
-
- doc_dir -- The path to other documentation files necessary to build
- the documentation. This files in this directory as well as
- the files in the 'html' subdirectory will be copied
- recursively into the output directory. (default '')
- main_sgml_file -- The path or name (if a doc_dir is given) of the SGML file
- that is the considered the main page of your documentation.
- (default: <module_name>-docs.sgml)
- version -- The version number of the module. If this is provided,
- a version.xml file containing the version will be created
- in the output directory during documentation generation.
-
- interactive -- Whether or not errors or warnings should prompt the user
- to continue or not. When this value is false, generation
- will continue despite warnings. (default False)
-
- virtual_root -- A temporary installation directory which is used as the root
- where the actual installation prefix lives; this is mostly
- useful for packagers, and should be set to what is given to
- make install as DESTDIR.
- """
-
- def __init__(self, args):
-
- # Parameters specific to scanning.
- self.module_name = ''
- self.source_dirs = []
- self.headers = []
- self.ignored_files = []
- self.namespace = ''
- self.decorator = ''
- self.deprecation_guard = ''
-
- # Parameters specific to gtkdoc-scanobj.
- self.cflags = ''
- self.ldflags = ''
- self.library_path = ''
-
- # Parameters specific to generation.
- self.output_dir = ''
- self.doc_dir = ''
- self.main_sgml_file = ''
-
- # Parameters specific to gtkdoc-fixxref.
- self.cross_reference_deps = []
-
- self.interactive = False
-
- self.logger = logging.getLogger('gtkdoc')
-
- for key, value in iter(args.items()):
- setattr(self, key, value)
-
- if not getattr(self, 'output_dir'):
- raise Exception('output_dir not specified.')
- if not getattr(self, 'module_name'):
- raise Exception('module_name not specified.')
- if not getattr(self, 'source_dirs') and not getattr(self, 'headers'):
- raise Exception('Neither source_dirs nor headers specified.' % key)
-
- # Make all paths absolute in case we were passed relative paths, since
- # we change the current working directory when executing subcommands.
- self.output_dir = os.path.abspath(self.output_dir)
- self.source_dirs = [os.path.abspath(x) for x in self.source_dirs]
- self.headers = [os.path.abspath(x) for x in self.headers]
- if self.library_path:
- self.library_path = os.path.abspath(self.library_path)
-
- if not self.main_sgml_file:
- self.main_sgml_file = self.module_name + "-docs.sgml"
-
- def generate(self, html=True):
- self.saw_warnings = False
-
- self._copy_doc_files_to_output_dir(html)
- self._write_version_xml()
- self._run_gtkdoc_scan()
- self._run_gtkdoc_scangobj()
- self._run_gtkdoc_mkdb()
-
- if not html:
- return
-
- self._run_gtkdoc_mkhtml()
- self._run_gtkdoc_fixxref()
-
- def _delete_file_if_exists(self, path):
- if not os.access(path, os.F_OK | os.R_OK):
- return
- self.logger.debug('deleting %s', path)
- os.unlink(path)
-
- def _create_directory_if_nonexistent(self, path):
- try:
- os.makedirs(path)
- except OSError as error:
- if error.errno != errno.EEXIST:
- raise
-
- def _raise_exception_if_file_inaccessible(self, path):
- if not os.path.exists(path) or not os.access(path, os.R_OK):
- raise Exception("Could not access file at: %s" % path)
-
- def _output_has_warnings(self, outputs):
- for output in outputs:
- if output and output.find('warning'):
- return True
- return False
-
- def _ask_yes_or_no_question(self, question):
- if not self.interactive:
- return True
-
- question += ' [y/N] '
- answer = None
- while answer != 'y' and answer != 'n' and answer != '':
- answer = raw_input(question).lower()
- return answer == 'y'
-
- def _run_command(self, args, env=None, cwd=None, print_output=True, ignore_warnings=False):
- if print_output:
- self.logger.debug("Running %s", args[0])
- self.logger.debug("Full command args: %s", str(args))
-
- process = subprocess.Popen(args, env=env, cwd=cwd,
- stdout=subprocess.PIPE,
- stderr=subprocess.PIPE)
- stdout, stderr = [b.decode("utf-8") for b in process.communicate()]
-
- if print_output:
- if stdout:
- if PY2:
- try:
- sys.stdout.write(stdout.encode("utf-8"))
- except UnicodeDecodeError:
- sys.stdout.write(stdout)
- else:
- sys.stdout.write(stdout)
- if stderr:
- if PY2:
- try:
- sys.stderr.write(stderr.encode("utf-8"))
- except UnicodeDecodeError:
- sys.stderr.write(stderr)
- else:
- sys.stderr.write(stderr)
-
- if process.returncode != 0:
- raise Exception('%s produced a non-zero return code %i'
- % (args[0], process.returncode))
-
- if not ignore_warnings and ('warning' in stderr or 'warning' in stdout):
- self.saw_warnings = True
- if not self._ask_yes_or_no_question('%s produced warnings, '
- 'try to continue?' % args[0]):
- raise Exception('%s step failed' % args[0])
-
- return stdout.strip()
-
- def _copy_doc_files_to_output_dir(self, html=True):
- if not self.doc_dir:
- self.logger.info('Not copying any files from doc directory,'
- ' because no doc directory given.')
- return
-
- def copy_file_replacing_existing(src, dest):
- if os.path.isdir(src):
- self.logger.debug('skipped directory %s', src)
- return
- if not os.access(src, os.F_OK | os.R_OK):
- self.logger.debug('skipped unreadable %s', src)
- return
-
- self._delete_file_if_exists(dest)
-
- self.logger.debug('created %s', dest)
- try:
- os.link(src, dest)
- except OSError:
- os.symlink(src, dest)
-
- def copy_all_files_in_directory(src, dest):
- for path in os.listdir(src):
- copy_file_replacing_existing(os.path.join(src, path),
- os.path.join(dest, path))
-
- self.logger.debug('Copying template files to output directory...')
- self._create_directory_if_nonexistent(self.output_dir)
- copy_all_files_in_directory(self.doc_dir, self.output_dir)
-
- if not html:
- return
-
- self.logger.debug('Copying HTML files to output directory...')
- html_src_dir = os.path.join(self.doc_dir, 'html')
- html_dest_dir = os.path.join(self.output_dir, 'html')
- self._create_directory_if_nonexistent(html_dest_dir)
-
- if os.path.exists(html_src_dir):
- copy_all_files_in_directory(html_src_dir, html_dest_dir)
-
- def _write_version_xml(self):
- if not self.version:
- self.logger.info('No version specified, so not writing version.xml')
- return
-
- version_xml_path = os.path.join(self.output_dir, 'version.xml')
- src_version_xml_path = os.path.join(self.doc_dir, 'version.xml')
-
- # Don't overwrite version.xml if it was in the doc directory.
- if os.path.exists(version_xml_path) and \
- os.path.exists(src_version_xml_path):
- return
-
- output_file = open(version_xml_path, 'w')
- output_file.write(self.version)
- output_file.close()
-
- def _ignored_files_basenames(self):
- return ' '.join([os.path.basename(x) for x in self.ignored_files])
-
- def _run_gtkdoc_scan(self):
- args = ['gtkdoc-scan',
- '--module=%s' % self.module_name,
- '--rebuild-types']
-
- if not self.headers:
- # Each source directory should be have its own "--source-dir=" prefix.
- args.extend(['--source-dir=%s' % path for path in self.source_dirs])
-
- if self.decorator:
- args.append('--ignore-decorators=%s' % self.decorator)
- if self.deprecation_guard:
- args.append('--deprecated-guards=%s' % self.deprecation_guard)
- if self.output_dir:
- args.append('--output-dir=%s' % self.output_dir)
-
- # We only need to pass the list of ignored files if the we are not using an explicit list of headers.
- if not self.headers:
- # gtkdoc-scan wants the basenames of ignored headers, so strip the
- # dirname. Different from "--source-dir", the headers should be
- # specified as one long string.
- ignored_files_basenames = self._ignored_files_basenames()
- if ignored_files_basenames:
- args.append('--ignore-headers=%s' % ignored_files_basenames)
-
- if self.headers:
- args.extend(self.headers)
-
- self._run_command(args)
-
- def _run_gtkdoc_scangobj(self):
- env = os.environ
- ldflags = self.ldflags
- if self.library_path:
- additional_ldflags = ''
- for arg in env.get('LDFLAGS', '').split(' '):
- if arg.startswith('-L'):
- additional_ldflags = '%s %s' % (additional_ldflags, arg)
- ldflags = ' "-L%s" %s ' % (self.library_path, additional_ldflags) + ldflags
- current_ld_library_path = env.get('LD_LIBRARY_PATH')
- if current_ld_library_path:
- env['LD_LIBRARY_PATH'] = '%s:%s' % (self.library_path, current_ld_library_path)
- else:
- env['LD_LIBRARY_PATH'] = self.library_path
-
- if ldflags:
- env['LDFLAGS'] = '%s %s' % (ldflags, env.get('LDFLAGS', ''))
- if self.cflags:
- env['CFLAGS'] = '%s %s' % (self.cflags, env.get('CFLAGS', ''))
-
- if 'CFLAGS' in env:
- self.logger.debug('CFLAGS=%s', env['CFLAGS'])
- if 'LDFLAGS' in env:
- self.logger.debug('LDFLAGS %s', env['LDFLAGS'])
- if 'RUN' in env:
- self.logger.debug('RUN=%s', env['RUN'])
- self._run_command(['gtkdoc-scangobj', '--module=%s' % self.module_name],
- env=env, cwd=self.output_dir)
-
- def _run_gtkdoc_mkdb(self):
- sgml_file = os.path.join(self.output_dir, self.main_sgml_file)
- self._raise_exception_if_file_inaccessible(sgml_file)
-
- args = ['gtkdoc-mkdb',
- '--module=%s' % self.module_name,
- '--main-sgml-file=%s' % sgml_file,
- '--source-suffixes=h,c,cpp,cc',
- '--output-format=xml',
- '--sgml-mode']
-
- if self.namespace:
- args.append('--name-space=%s' % self.namespace)
-
- ignored_files_basenames = self._ignored_files_basenames()
- if ignored_files_basenames:
- args.append('--ignore-files=%s' % ignored_files_basenames)
-
- # Each directory should be have its own "--source-dir=" prefix.
- args.extend(['--source-dir=%s' % path for path in self.source_dirs])
- self._run_command(args, cwd=self.output_dir)
-
- def _run_gtkdoc_mkhtml(self):
- html_dest_dir = os.path.join(self.output_dir, 'html')
- if not os.path.isdir(html_dest_dir):
- raise Exception("%s is not a directory, could not generate HTML"
- % html_dest_dir)
- elif not os.access(html_dest_dir, os.X_OK | os.R_OK | os.W_OK):
- raise Exception("Could not access %s to generate HTML"
- % html_dest_dir)
-
- # gtkdoc-mkhtml expects the SGML path to be absolute.
- sgml_file = os.path.join(os.path.abspath(self.output_dir),
- self.main_sgml_file)
- self._raise_exception_if_file_inaccessible(sgml_file)
-
- self._run_command(['gtkdoc-mkhtml', self.module_name, sgml_file],
- cwd=html_dest_dir)
-
- def _run_gtkdoc_fixxref(self):
- args = ['gtkdoc-fixxref',
- '--module=%s' % self.module_name,
- '--module-dir=html',
- '--html-dir=html']
- args.extend(['--extra-dir=%s' % extra_dir for extra_dir in self.cross_reference_deps])
- self._run_command(args, cwd=self.output_dir, ignore_warnings=True)
-
- def rebase_installed_docs(self):
- if not os.path.isdir(self.output_dir):
- raise Exception("Tried to rebase documentation before generating it.")
- html_dir = os.path.join(self.virtual_root + self.prefix, 'share', 'gtk-doc', 'html', self.module_name)
- if not os.path.isdir(html_dir):
- return
- args = ['gtkdoc-rebase',
- '--relative',
- '--html-dir=%s' % html_dir]
- args.extend(['--other-dir=%s' % extra_dir for extra_dir in self.cross_reference_deps])
- if self.virtual_root:
- args.extend(['--dest-dir=%s' % self.virtual_root])
- self._run_command(args, cwd=self.output_dir)
-
- def api_missing_documentation(self):
- unused_doc_file = os.path.join(self.output_dir, self.module_name + "-unused.txt")
- if not os.path.exists(unused_doc_file) or not os.access(unused_doc_file, os.R_OK):
- return []
- return open(unused_doc_file).read().splitlines()
-
-class PkgConfigGTKDoc(GTKDoc):
-
- """Class reads a library's pkgconfig file to guess gtkdoc parameters.
-
- Some gtkdoc parameters can be guessed by reading a library's pkgconfig
- file, including the cflags, ldflags and version parameters. If you
- provide these parameters as well, they will be appended to the ones
- guessed via the pkgconfig file.
-
- Keyword arguments:
- pkg_config_path -- Path to the pkgconfig file for the library. Required.
- """
-
- def __init__(self, pkg_config_path, args):
- super(PkgConfigGTKDoc, self).__init__(args)
-
- pkg_config = os.environ.get('PKG_CONFIG', 'pkg-config')
-
- if not os.path.exists(pkg_config_path):
- raise Exception('Could not find pkg-config file at: %s'
- % pkg_config_path)
-
- self.cflags += " " + self._run_command([pkg_config,
- pkg_config_path,
- '--cflags'], print_output=False)
- self.ldflags += " " + self._run_command([pkg_config,
- pkg_config_path,
- '--libs'], print_output=False)
- self.version = self._run_command([pkg_config,
- pkg_config_path,
- '--modversion'], print_output=False)
- self.prefix = self._run_command([pkg_config,
- pkg_config_path,
- '--variable=prefix'], print_output=False)