[GTK] Print API missing documentation when generating gtkdoc

https://bugs.webkit.org/show_bug.cgi?id=95703

Patch by Martin Robinson <mrobinson@igalia.com> on 2012-09-04
Reviewed by Carlos Garcia Campos.

Print out API missing documentation when generating gtkdoc. This makes it
easier to fix documentation errors.

* gtk/generate-gtkdoc:
(print_missing_api): Added.
(generate_doc): Inline the rebase step, since it now reports an error
when you try to rebase without generating documentation first.
* gtk/gtkdoc.py:
(GTKDoc.rebase_installed_docs): Raise an error when rebasing without
generating documentation first to enable a small cleanup at the caller.
(GTKDoc.api_missing_documentation): Added.

git-svn-id: http://svn.webkit.org/repository/webkit/trunk@127475 268f45cc-cd09-0410-ab3c-d52691b4dbfc
parent 85558650
2012-09-04 Martin Robinson <mrobinson@igalia.com>
[GTK] Print API missing documentation when generating gtkdoc
https://bugs.webkit.org/show_bug.cgi?id=95703
Reviewed by Carlos Garcia Campos.
Print out API missing documentation when generating gtkdoc. This makes it
easier to fix documentation errors.
* gtk/generate-gtkdoc:
(print_missing_api): Added.
(generate_doc): Inline the rebase step, since it now reports an error
when you try to rebase without generating documentation first.
* gtk/gtkdoc.py:
(GTKDoc.rebase_installed_docs): Raise an error when rebasing without
generating documentation first to enable a small cleanup at the caller.
(GTKDoc.api_missing_documentation): Added.
2012-09-04 Vincent Scheib <scheib@chromium.org>
[Chromium] Allow asyncronous response of pointer lock requests in layout tests.
......
......@@ -137,18 +137,20 @@ def get_webkit1_options(gtk_version):
})
return options
def generate_doc(pkg_config_path, options):
generator = gtkdoc.PkgConfigGTKDoc(pkg_config_path, options)
def print_missing_api(generator):
missing_api = generator.api_missing_documentation()
if not missing_api:
return
print "\nThe following API are missing documentation:"
for api in missing_api:
print "\t%s" % api
def generate_doc(generator):
generator.generate(html='--skip-html' not in sys.argv)
if generator.saw_warnings:
print_missing_api(generator)
return generator.saw_warnings
def rebase_installed_docs(pkg_config_path, options):
if not os.path.isdir(options['output_dir']):
print "Documentation was not generated"
return
generator = gtkdoc.PkgConfigGTKDoc(pkg_config_path, options)
generator.rebase_installed_docs()
configure_logging()
# We need to add the JavaScriptCore build directory to the PKG_CONFIG_PATH
......@@ -165,22 +167,23 @@ if not os.path.exists(pkg_config_path):
pkg_config_path = common.build_path('Source', 'WebKit', 'gtk', 'webkit-1.0.pc')
if os.path.exists(pkg_config_path):
options = get_webkit1_options(common.gtk_version_of_pkg_config_file(pkg_config_path))
generator = gtkdoc.PkgConfigGTKDoc(pkg_config_path, options)
if '--rebase' not in sys.argv:
print "Generating WebKit1 documentation..."
saw_webkit1_warnings = generate_doc(pkg_config_path, options)
saw_webkit1_warnings = generate_doc(generator)
else:
print "Rebasing WebKit1 documentation..."
rebase_installed_docs(pkg_config_path, options)
generator.rebase_installed_docs()
# WebKit2 might not be enabled, so check for the pkg-config file before building documentation.
pkg_config_path = common.build_path('Source', 'WebKit2', 'webkit2gtk-3.0.pc')
if os.path.exists(pkg_config_path):
options = get_webkit2_options()
generator = gtkdoc.PkgConfigGTKDoc(pkg_config_path, get_webkit2_options())
if '--rebase' not in sys.argv:
print "\nGenerating WebKit2 documentation..."
saw_webkit2_warnings = generate_doc(pkg_config_path, options)
saw_webkit2_warnings = generate_doc(generator)
else:
print "\nRebasing WebKit2 documentation..."
rebase_installed_docs(pkg_config_path, options)
generator.rebase_installed_docs()
sys.exit(saw_webkit1_warnings or saw_webkit2_warnings)
......@@ -361,6 +361,8 @@ class GTKDoc(object):
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
......@@ -372,6 +374,11 @@ class GTKDoc(object):
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):
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment