/usr/share/gtk-doc/python/gtkdoc/check.py is in gtk-doc-tools 1.27-3.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 | # -*- python; coding: utf-8 -*-
#
# gtk-doc - GTK DocBook documentation generator.
# Copyright (C) 2007 David Nečas
# 2007-2017 Stefan Sauer
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2 of the License, or
# (at your option) any later version.
#
# This program 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 General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
#
"""
The check tool runs various tests on built documentation and outputs test
results. Can be run druring make check, by adding this to the documentations
Makefile.am: TESTS = $(GTKDOC_CHECK).
"""
# Support both Python 2 and 3
from __future__ import print_function
import os
import re
from glob import glob
from . import common
class FileFormatError(Exception):
pass
def grep(regexp, lines, what):
pattern = re.compile(regexp)
for line in lines:
for match in re.finditer(pattern, line):
return match.group(1)
raise FileFormatError(what)
def check_empty(filename):
with open(filename, "rb") as f:
count = sum(1 for line in f if line.strip())
return count
def check_includes(filename):
# Check that each XML file in the xml directory is included in doc_main_file
with common.open_text(filename) as f:
lines = f.read().splitlines()
num_missing = 0
for include in glob('xml/*.xml'):
try:
next(line for line in lines if include in line)
except StopIteration:
num_missing += 1
print('%s:1:E: doesn\'t appear to include "%s"' % (filename, include))
return num_missing
def get_variable(env, lines, variable):
value = env.get(variable,
grep(r'^\s*' + variable + r'\s*=\s*(\S+)', lines, variable))
return value
def read_file(filename):
with common.open_text(filename) as f:
return f.read().splitlines()
def run_tests(workdir, doc_module, doc_main_file):
checks = 4
print('Running suite(s): gtk-doc-' + doc_module)
# Test #1
statusfilename = os.path.join(workdir, doc_module + '-undocumented.txt')
statusfile = read_file(statusfilename)
try:
undocumented = int(grep(r'^(\d+)\s+not\s+documented\.\s*$',
statusfile, 'number of undocumented symbols'))
incomplete = int(grep(r'^(\d+)\s+symbols?\s+incomplete\.\s*$',
statusfile, 'number of incomplete symbols'))
except FileFormatError as e:
print('Cannot find %s in %s' % (str(e), statusfilename))
return checks # consider all failed
total = undocumented + incomplete
if total:
print(doc_module + '-undocumented.txt:1:E: %d undocumented or incomplete symbols' % total)
# Test #2
undeclared = check_empty(os.path.join(workdir, doc_module + '-undeclared.txt'))
if undeclared:
print(doc_module + '-undeclared.txt:1:E: %d undeclared symbols\n' % undeclared)
# Test #3
unused = check_empty(os.path.join(workdir, doc_module + '-unused.txt'))
if unused:
print(doc_module + '-unused.txt:1:E: %d unused documentation entries\n' % unused)
# Test #4
missing_includes = check_includes(os.path.join(workdir, doc_main_file))
# Test Summary
failed = (total > 0) + (undeclared != 0) + (unused != 0) + (missing_includes != 0)
rate = 100.0 * (checks - failed) / checks
print("%.1f%%: Checks %d, Failures: %d" % (rate, checks, failed))
return failed
def run(options=None):
"""Runs the tests.
Returns:
int: a system exit code.
"""
# Get parameters from test env, if not there try to grab them from the makefile
# We like Makefile.am more but builddir does not necessarily contain one.
makefilename = 'Makefile.am'
if not os.path.exists(makefilename):
makefilename = 'Makefile'
makefile = []
try:
makefile = read_file(makefilename)
except (OSError, IOError):
pass
# For historic reasons tests are launched in srcdir
workdir = os.environ.get('BUILDDIR', None)
if not workdir:
workdir = '.'
try:
doc_module = get_variable(os.environ, makefile, 'DOC_MODULE')
doc_main_file = get_variable(os.environ, makefile, 'DOC_MAIN_SGML_FILE')
except FileFormatError as e:
print('Cannot find %s in %s' % (str(e), makefilename))
return 1
doc_main_file = doc_main_file.replace('$(DOC_MODULE)', doc_module)
return run_tests(workdir, doc_module, doc_main_file)
|