Log Message
Merge 164632 - [GTK] generate-gtkdoc should not generate documentation for source files for unbuilt source files https://bugs.webkit.org/show_bug.cgi?id=128417
Reviewed by Carlos Garcia Campos. .: * Source/cmake/OptionsGTK.cmake: Define the paths to the pkgconfig files here, so that they may one day be used in the webkitdom config file generation. Source/WebCore: * bindings/gobject/GNUmakefile.am: Generate a config file for webkitdom documentation generation. Source/WebKit: * PlatformGTK.cmake: Correct the definition of WebKitGTK_ENUM_GENERATION_HEADERS and generate a gtkdoc-webkitgtk.cfg file to be used by generate-gtkdoc. Source/WebKit/gtk: * GNUmakefile.am: Generate a config file for generate-gtkdoc. Source/WebKit2: * GNUmakefile.am: Generate a config file for generate-gtkdoc. * PlatformGTK.cmake: Ditto. Tools: * gtk/GNUmakefile.am: Make the documentation process depend on the configuration files. * gtk/generate-gtkdoc: Switch from using hard-coded configurations to reading them from a makefile. This allows accepting a header list from the build system, which can be used to dynamically build a list of ignored files. We can ignore any source file that doesn't have a corresponding header file on the header list. * gtk/gtkdoc.py: Now accept a headers parameter, which can be used instead of passing just source directories to gtkdoc-scan. Conflicts: ChangeLog Source/WebCore/ChangeLog Source/WebKit/ChangeLog Source/WebKit/gtk/ChangeLog Source/WebKit2/ChangeLog Tools/ChangeLog
Modified Paths
- releases/WebKitGTK/webkit-2.4/GNUmakefile.am
- releases/WebKitGTK/webkit-2.4/Source/WebCore/bindings/gobject/GNUmakefile.am
- releases/WebKitGTK/webkit-2.4/Source/WebKit/PlatformGTK.cmake
- releases/WebKitGTK/webkit-2.4/Source/WebKit/gtk/GNUmakefile.am
- releases/WebKitGTK/webkit-2.4/Source/WebKit2/GNUmakefile.am
- releases/WebKitGTK/webkit-2.4/Source/WebKit2/PlatformGTK.cmake
- releases/WebKitGTK/webkit-2.4/Source/cmake/OptionsGTK.cmake
- releases/WebKitGTK/webkit-2.4/Tools/gtk/GNUmakefile.am
- releases/WebKitGTK/webkit-2.4/Tools/gtk/generate-gtkdoc
- releases/WebKitGTK/webkit-2.4/Tools/gtk/gtkdoc.py
Diff
Modified: releases/WebKitGTK/webkit-2.4/GNUmakefile.am (168708 => 168709)
--- releases/WebKitGTK/webkit-2.4/GNUmakefile.am 2014-05-13 19:28:38 UTC (rev 168708)
+++ releases/WebKitGTK/webkit-2.4/GNUmakefile.am 2014-05-13 19:29:03 UTC (rev 168709)
@@ -132,6 +132,15 @@
typelibsdir := $(libdir)/girepository-1.0
endif
+webkit1_pkg_config_file = Source/WebKit/gtk/webkitgtk-@WEBKITGTK_API_MAJOR_VERSION@.@WEBKITGTK_API_MINOR_VERSION@.pc
+webkit2_pkg_config_file = Source/WebKit2/webkit2gtk-@WEBKITGTK_API_MAJOR_VERSION@.@WEBKITGTK_API_MINOR_VERSION@.pc
+
+if ENABLE_WEBKIT2
+webkitdom_pkgconfig_file = $(webkit2_pkg_config_file)
+else
+webkitdom_pkgconfig_file = $(webkit1_pkg_config_file)
+endif
+
# We do not care at all about this implicit built-in make rules,
# disable them to save some build time
%: %.c
@@ -290,4 +299,4 @@
@mkdir -p $(distdir)/Documentation/webkitdomgtk/html
@mkdir -p $(distdir)/Documentation/webkitdomgtk/tmpl
@-cp ./Documentation/webkitdomgtk/tmpl/*.sgml $(distdir)/Documentation/webkitdomgtk/tmpl
- @cp ./Documentation/webkitdomgtk/html/* $(distdir)/Documentation/webkitdomgtk/html
\ No newline at end of file
+ @cp ./Documentation/webkitdomgtk/html/* $(distdir)/Documentation/webkitdomgtk/html
Modified: releases/WebKitGTK/webkit-2.4/Source/WebCore/bindings/gobject/GNUmakefile.am (168708 => 168709)
--- releases/WebKitGTK/webkit-2.4/Source/WebCore/bindings/gobject/GNUmakefile.am 2014-05-13 19:28:38 UTC (rev 168708)
+++ releases/WebKitGTK/webkit-2.4/Source/WebCore/bindings/gobject/GNUmakefile.am 2014-05-13 19:29:03 UTC (rev 168709)
@@ -578,12 +578,15 @@
-fvisibility=hidden \
$(global_cflags)
+webkitgtk_gdom_include_dirs = \
+ -I$(WebCore)/bindings \
+ -I$(WebCore)/bindings/gobject \
+ -I$(GENSOURCES_WEBKITDOM)
+
libGObjectDOMBindings_la_CPPFLAGS = \
-DBUILDING_WebCore \
-DBUILDING_WEBKIT \
- -I$(WebCore)/bindings \
- -I$(WebCore)/bindings/gobject \
- -I$(GENSOURCES_WEBKITDOM) \
+ $(webkitgtk_gdom_include_dirs) \
$(global_cppflags) \
$(platform_cppflags) \
$(platformgtk_cppflags) \
@@ -594,3 +597,13 @@
$(FREETYPE_CFLAGS) \
$(GLIB_CFLAGS) \
$(LIBSOUP_CFLAGS)
+
+gtkdoc-webkitdom.cfg: $(WebCore)/bindings/gobject/GNUmakefile.am $(srcdir)/Tools/gtk/GNUmakefile.am
+ $(AM_V_GEN)echo "[webkitdomgtk]" > $@ && \
+ echo "pkgconfig_file=$(webkitdom_pkgconfig_file)" >> $@ && \
+ echo "namespace=webkit_dom" >> $@ && \
+ echo "doc_dir=DerivedSources/webkitdom/docs" >> $@ && \
+ echo -e "cflags=-I$(srcdir)/Source $(webkitgtk_gdom_include_dirs)" >> $@ && \
+ echo "source_dirs=$(top_builddir)/DerivedSources/webkitdom $(srcdir)/Source/WebCore/bindings/gobject" >> $@ && \
+ echo "headers=$(webkitgtk_gdom_built_h_api) DerivedSources/webkitdom/WebKitDOMDeprecated.h" >> $@
+BUILT_SOURCES += gtkdoc-webkitdom.cfg
Modified: releases/WebKitGTK/webkit-2.4/Source/WebKit/PlatformGTK.cmake (168708 => 168709)
--- releases/WebKitGTK/webkit-2.4/Source/WebKit/PlatformGTK.cmake 2014-05-13 19:28:38 UTC (rev 168708)
+++ releases/WebKitGTK/webkit-2.4/Source/WebKit/PlatformGTK.cmake 2014-05-13 19:29:03 UTC (rev 168709)
@@ -1,7 +1,7 @@
file(MAKE_DIRECTORY ${DERIVED_SOURCES_WEBKITGTK_DIR})
file(MAKE_DIRECTORY ${DERIVED_SOURCES_WEBKITGTK_API_DIR})
configure_file(gtk/webkit/webkitversion.h.in ${DERIVED_SOURCES_WEBKITGTK_API_DIR}/webkitversion.h)
-configure_file(gtk/webkit.pc.in ${CMAKE_BINARY_DIR}/Source/WebKit/gtk/webkitgtk-${WEBKITGTK_API_VERSION}.pc @ONLY)
+configure_file(gtk/webkit.pc.in ${WebKit_PKGCONFIG_FILE} @ONLY)
add_definitions(-DPACKAGE_LOCALE_DIR="${CMAKE_INSTALL_FULL_LOCALEDIR}")
@@ -156,7 +156,7 @@
# To generate webkitenumtypes.h we want to use all installed headers, except webkitenumtypes.h itself.
set(WebKitGTK_ENUM_GENERATION_HEADERS ${WebKitGTK_INSTALLED_HEADERS})
-list(REMOVE_ITEM WebKitGTK_ENUM_GENERATION_HEADERS ${DERIVED_SOURCES_WEBKIT2GTK_API_DIR}/webkitenumtypes.h)
+list(REMOVE_ITEM WebKitGTK_ENUM_GENERATION_HEADERS ${DERIVED_SOURCES_WEBKITGTK_API_DIR}/webkitenumtypes.h)
add_custom_command(
OUTPUT ${DERIVED_SOURCES_WEBKITGTK_API_DIR}/webkitenumtypes.h
${DERIVED_SOURCES_WEBKITGTK_API_DIR}/webkitenumtypes.cpp
@@ -229,3 +229,17 @@
install(FILES ${CMAKE_BINARY_DIR}/WebKit-${WEBKITGTK_API_VERSION}.typelib
DESTINATION ${INTROSPECTION_INSTALL_TYPELIBDIR}
)
+
+file(WRITE ${CMAKE_BINARY_DIR}/gtkdoc-webkitgtk.cfg
+ "[webkitgtk]\n"
+ "pkgconfig_file=${WebKit_PKGCONFIG_FILE}\n"
+ "namespace=webkit\n"
+ "cflags=-I${DERIVED_SOURCES_DIR}\n"
+ " -I${CMAKE_SOURCE_DIR}\n"
+ " -I${CMAKE_SOURCE_DIR}/Source\n"
+ " -I${CMAKE_SOURCE_DIR}/_javascript_Core/ForwardingHeaders\n"
+ "doc_dir=${WEBKIT_DIR}/gtk/docs\n"
+ "source_dirs=${WEBKIT_DIR}/gtk/webkit\n"
+ " ${DERIVED_SOURCES_WEBKITGTK_API_DIR}\n"
+ "headers=${WebKitGTK_ENUM_GENERATION_HEADERS}\n"
+)
Modified: releases/WebKitGTK/webkit-2.4/Source/WebKit/gtk/GNUmakefile.am (168708 => 168709)
--- releases/WebKitGTK/webkit-2.4/Source/WebKit/gtk/GNUmakefile.am 2014-05-13 19:28:38 UTC (rev 168708)
+++ releases/WebKitGTK/webkit-2.4/Source/WebKit/gtk/GNUmakefile.am 2014-05-13 19:29:03 UTC (rev 168709)
@@ -379,6 +379,17 @@
&& cp xgen-gtc $@ \
&& rm -f xgen-gtc
+gtkdoc-webkitgtk.cfg: $(WebKit)/GNUmakefile.am $(srcdir)/Tools/gtk/GNUmakefile.am
+ $(AM_V_GEN)echo "[webkitgtk]" > $@ && \
+ echo "pkgconfig_file=$(webkit1_pkg_config_file)" >> $@ && \
+ echo "namespace=webkit" >> $@ && \
+ echo -e "cflags=$(libwebkitgtk_@WEBKITGTK_API_MAJOR_VERSION@_@WEBKITGTK_API_MINOR_VERSION@_la_CPPFLAGS)" >> $@ && \
+ echo "doc_dir=$(srcdir)/Source/WebKit/gtk/docs" >> $@ && \
+ echo -e "source_dirs=$(srcdir)/Source/WebKit/gtk/webkit\n \
+ Source/WebKit/gtk/webkit" >> $@ && \
+ echo -e "headers=$(webkitgtk_static_h_api) Source/WebKit/gtk/webkit/webkitversion.h" >> $@
+BUILT_SOURCES += gtkdoc-webkitgtk.cfg
+
EXTRA_DIST += \
$(WebKit)/ChangeLog \
$(WebKit)/NEWS \
Modified: releases/WebKitGTK/webkit-2.4/Source/WebKit2/GNUmakefile.am (168708 => 168709)
--- releases/WebKitGTK/webkit-2.4/Source/WebKit2/GNUmakefile.am 2014-05-13 19:28:38 UTC (rev 168708)
+++ releases/WebKitGTK/webkit-2.4/Source/WebKit2/GNUmakefile.am 2014-05-13 19:29:03 UTC (rev 168709)
@@ -809,6 +809,25 @@
-fvisibility-inlines-hidden \
$(global_cxxflags)
+# It would be nice to use the CPPFLAGS from the WebKit2 library here, but the prefix
+# header doesn't seem to play nicely with the gtkdoc tools.
+gtkdoc-webkit2gtk.cfg: $(WebKit2)/GNUmakefile.am $(WebKit2)/GNUmakefile.list.am
+ $(AM_V_GEN)echo "[webkit2gtk]" > $@ && \
+ echo "pkgconfig_file=$(webkit2_pkg_config_file)" >> $@ && \
+ echo "namespace=webkit" >> $@ && \
+ echo -e "cflags=-I$(srcdir)/Source\n \
+ -I$(WebKit2)/UIProcess/API/gtk\n \
+ -IDerivedSources/webkit2gtk/include\n \
+ -IDerivedSources/WebKit2/webkit2gtk\n" >> $@ && \
+ echo "doc_dir=$(WebKit2)/UIProcess/API/gtk/docs" >> $@ && \
+ echo -e "source_dirs=$(WebKit2)/UIProcess/API/gtk\n \
+ $(WebKit2)/WebProcess/InjectedBundle/API/gtk\n \
+ DerivedSources/WebKit2/webkit2gtk/webkit2\n" >> $@ && \
+ echo -e "headers=$(webkit2gtk_ui_h_api)\n \
+ $(webkit2gtk_web_extension_h_api)\n \
+ DerivedSources/WebKit2/webkit2gtk/webkit2/WebKitVersion.h" >> $@
+BUILT_SOURCES += gtkdoc-webkit2gtk.cfg
+
EXTRA_DIST += \
$(WebKit2)/UIProcess/API/gtk/docs/webkit2gtk-docs.sgml \
$(WebKit2)/UIProcess/API/gtk/docs/webkit2gtk-sections.txt \
Modified: releases/WebKitGTK/webkit-2.4/Source/WebKit2/PlatformGTK.cmake (168708 => 168709)
--- releases/WebKitGTK/webkit-2.4/Source/WebKit2/PlatformGTK.cmake 2014-05-13 19:28:38 UTC (rev 168708)
+++ releases/WebKitGTK/webkit-2.4/Source/WebKit2/PlatformGTK.cmake 2014-05-13 19:29:03 UTC (rev 168709)
@@ -4,7 +4,7 @@
file(MAKE_DIRECTORY ${FORWARDING_HEADERS_WEBKIT2GTK_EXTENSION_DIR})
configure_file(UIProcess/API/gtk/WebKitVersion.h.in ${DERIVED_SOURCES_WEBKIT2GTK_API_DIR}/WebKitVersion.h)
-configure_file(webkit2gtk.pc.in ${CMAKE_BINARY_DIR}/Source/WebKit2/webkit2gtk-${WEBKITGTK_API_VERSION}.pc @ONLY)
+configure_file(webkit2gtk.pc.in ${WebKit2_PKGCONFIG_FILE} @ONLY)
add_definitions(-DWEBKIT2_COMPILATION)
add_definitions(-DLIBEXECDIR="${CMAKE_INSTALL_FULL_LIBEXECDIR}")
@@ -788,3 +788,18 @@
${CMAKE_BINARY_DIR}/WebKit2WebExtension-${WEBKITGTK_API_VERSION}.typelib
DESTINATION ${INTROSPECTION_INSTALL_TYPELIBDIR}
)
+
+file(WRITE ${CMAKE_BINARY_DIR}/gtkdoc-webkit2gtk.cfg
+ "[webkit2gtk]\n"
+ "pkgconfig_file=${WebKit2_PKGCONFIG_FILE}\n"
+ "namespace=webkit\n"
+ "cflags=-I${CMAKE_SOURCE_DIR}/Source\n"
+ " -I${WEBKIT2_DIR}/UIProcess/API/gtk\n"
+ " -I${DERIVED_SOURCES_WEBKIT2GTK_DIR}\n"
+ " -I${FORWARDING_HEADERS_WEBKIT2GTK_DIR}\n"
+ "doc_dir=${WEBKIT2_DIR}/UIProcess/API/gtk/docs\n"
+ "source_dirs=${WEBKIT2_DIR}/UIProcess/API/gtk\n"
+ " ${WEBKIT2_DIR}/WebProcess/InjectedBundle/API/gtk\n"
+ " ${DERIVED_SOURCES_WEBKIT2GTK_API_DIR}\n"
+ "headers=${WebKit2GTK_ENUM_GENERATION_HEADERS} ${WebKit2WebExtension_INSTALLED_HEADERS}\n"
+)
Modified: releases/WebKitGTK/webkit-2.4/Source/cmake/OptionsGTK.cmake (168708 => 168709)
--- releases/WebKitGTK/webkit-2.4/Source/cmake/OptionsGTK.cmake 2014-05-13 19:28:38 UTC (rev 168708)
+++ releases/WebKitGTK/webkit-2.4/Source/cmake/OptionsGTK.cmake 2014-05-13 19:29:03 UTC (rev 168709)
@@ -274,6 +274,10 @@
set(FORWARDING_HEADERS_DIR ${DERIVED_SOURCES_DIR}/ForwardingHeaders)
set(FORWARDING_HEADERS_WEBKIT2GTK_DIR ${FORWARDING_HEADERS_DIR}/webkit2gtk)
set(FORWARDING_HEADERS_WEBKIT2GTK_EXTENSION_DIR ${FORWARDING_HEADERS_DIR}/webkit2gtk-webextension)
+
+set(WebKit_PKGCONFIG_FILE ${CMAKE_BINARY_DIR}/Source/WebKit/gtk/webkitgtk-${WEBKITGTK_API_VERSION}.pc)
+set(WebKit2_PKGCONFIG_FILE ${CMAKE_BINARY_DIR}/Source/WebKit2/webkit2gtk-${WEBKITGTK_API_VERSION}.pc)
+
set(SHOULD_INSTALL_JS_SHELL ON)
# Push of rbp is needed after JSC JIT uses CStack. See http://wkbug.com/127777.
Modified: releases/WebKitGTK/webkit-2.4/Tools/gtk/GNUmakefile.am (168708 => 168709)
--- releases/WebKitGTK/webkit-2.4/Tools/gtk/GNUmakefile.am 2014-05-13 19:28:38 UTC (rev 168708)
+++ releases/WebKitGTK/webkit-2.4/Tools/gtk/GNUmakefile.am 2014-05-13 19:29:03 UTC (rev 168709)
@@ -10,21 +10,23 @@
.PHONY : docs
DISTCLEANFILES += docs-build.stamp
-docs_build_stamp_list = \
+docs_build_dependencies = \
Source/WebKit/gtk/docs/webkitenvironment.xml
if ENABLE_WEBKIT1
-docs_build_stamp_list += \
+docs_build_dependencies += \
libwebkitgtk-@WEBKITGTK_API_MAJOR_VERSION@.@WEBKITGTK_API_MINOR_VERSION@.la \
Source/WebKit/gtk/docs/webkitgtk-docs.sgml \
- Source/WebKit/gtk/docs/webkitgtk-sections.txt
+ Source/WebKit/gtk/docs/webkitgtk-sections.txt \
+ gtkdoc-webkitgtk.cfg
endif
if ENABLE_WEBKIT2
-docs_build_stamp_list += \
+docs_build_dependencies += \
libwebkit2gtk-@WEBKITGTK_API_MAJOR_VERSION@.@WEBKITGTK_API_MINOR_VERSION@.la \
Source/WebKit2/UIProcess/API/gtk/docs/webkit2gtk-docs.sgml \
- Source/WebKit2/UIProcess/API/gtk/docs/webkit2gtk-sections.txt
+ Source/WebKit2/UIProcess/API/gtk/docs/webkit2gtk-sections.txt \
+ gtkdoc-webkit2gtk.cfg
endif
$(top_builddir)/DerivedSources/webkitdom/docs/webkitdomgtk-docs.sgml: $(gdom_symbol_files) $(srcdir)/Tools/gtk/generate-webkitdom-doc-files
@@ -39,12 +41,13 @@
$(top_builddir)/DerivedSources/webkitdom/docs/webkitdomgtk-docs.sgml \
$(top_builddir)/DerivedSources/webkitdom/docs/webkitdomgtk-sections.txt
-docs_build_stamp_list += \
+docs_build_dependencies += \
libGObjectDOMBindings.la \
$(top_builddir)/DerivedSources/webkitdom/docs/webkitdomgtk-docs.sgml \
- $(top_builddir)/DerivedSources/webkitdom/docs/webkitdomgtk-sections.txt
+ $(top_builddir)/DerivedSources/webkitdom/docs/webkitdomgtk-sections.txt \
+ gtkdoc-webkitdom.cfg
-docs-build.stamp: $(docs_build_stamp_list)
+docs-build.stamp: $(docs_build_dependencies)
CC=$(CC) $(srcdir)/Tools/gtk/generate-gtkdoc
@touch docs-build.stamp
Modified: releases/WebKitGTK/webkit-2.4/Tools/gtk/generate-gtkdoc (168708 => 168709)
--- releases/WebKitGTK/webkit-2.4/Tools/gtk/generate-gtkdoc 2014-05-13 19:28:38 UTC (rev 168708)
+++ releases/WebKitGTK/webkit-2.4/Tools/gtk/generate-gtkdoc 2014-05-13 19:29:03 UTC (rev 168709)
@@ -15,6 +15,9 @@
# License along with this library; if not, write to the Free Software
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
+from __future__ import print_function
+from ConfigParser import SafeConfigParser
+
import argparse
import common
import glob
@@ -23,9 +26,6 @@
import os.path
import sys
-sys.path.insert(0, os.path.join(os.path.dirname(__file__), "../jhbuild"))
-import jhbuildrc_common
-
def configure_logging(verbose):
level = logging.DEBUG if verbose else logging.INFO
logger = logging.getLogger('gtkdoc')
@@ -38,183 +38,119 @@
else:
handler.setFormatter(logging.Formatter('%(message)s'))
-
-def get_gtkdoc_module_paths(xref_dep_packages):
- deps = []
- html_dir = os.path.join('share', 'gtk-doc', 'html')
-
- for package in xref_dep_packages:
- prefix = common.prefix_of_pkg_config_file(package)
- if prefix is None:
- continue
- for module in xref_dep_packages[package]:
- deps.append(os.path.join(prefix, html_dir, module))
-
- return deps
-
-
-def get_common_xref_deps():
- return {
+def get_gtkdoc_module_paths(gtk_version):
+ dependent_packages = {
'glib-2.0' : ['glib', 'gobject', 'gio'],
'libsoup-2.4' : ['libsoup-2.4'],
'gdk-pixbuf-2.0': ['gdk-pixbuf']
}
-
-def webkitdom_docs_html_path():
- return common.build_path('Documentation', 'webkitdomgtk', 'html')
-
-def get_webkit2_options(virtual_root):
- api_path = jhbuildrc_common.top_level_path('Source', 'WebKit2', 'UIProcess', 'API', 'gtk')
- injected_bundle_api_path = jhbuildrc_common.top_level_path('Source', 'WebKit2', 'WebProcess', 'InjectedBundle', 'API', 'gtk')
-
- if common.is_cmake_build():
- generated_api_path = common.build_path('DerivedSources', 'webkit2gtk', 'webkit2')
+ if gtk_version == 3:
+ dependent_packages.update({'gtk+-3.0' : ['gtk3', 'gdk3']})
else:
- generated_api_path = common.build_path('DerivedSources', 'WebKit2', 'webkit2gtk', 'webkit2')
+ dependent_packages.update({'gtk+-2.0' : ['gtk', 'gdk']})
- xref_deps = get_common_xref_deps().copy()
- xref_deps.update({
- 'gtk+-3.0' : ['gtk3', 'gdk3']
- })
+ paths = []
+ html_dir = os.path.join('share', 'gtk-doc', 'html')
+ for package, modules in dependent_packages.iteritems():
+ prefix = common.prefix_of_pkg_config_file(package)
+ if prefix is None:
+ continue
+ for module in modules:
+ paths.append(os.path.join(prefix, html_dir, module))
+ # This technically is not needed for the GObject DOM bindings documentation itself,
+ # but adding it doesn't hurt and allows us to avoid a check here.
+ paths.append(common.build_path('Documentation', 'webkitdomgtk', 'html'))
+ return paths
- def src_path(*args):
- return os.path.join(api_path, *args)
+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{0}".format(api))
- options = {
- 'decorator': 'WEBKIT_API|WEBKIT_DEPRECATED|WEBKIT_DEPRECATED_FOR\(.+\)',
- 'deprecation_guard': 'WEBKIT_DISABLE_DEPRECATED',
- 'library_path' : common.library_build_path(),
- 'virtual_root' : virtual_root,
- 'module_name' : 'webkit2gtk',
- 'namespace' : 'webkit',
- 'doc_dir' : src_path('docs'),
- 'output_dir' : common.build_path('Documentation', 'webkit2gtk'),
- 'source_dirs' : [src_path(), generated_api_path, injected_bundle_api_path],
- 'cflags' :
- # Common paths
- ' -I' + jhbuildrc_common.top_level_path('Source') + \
- ' -I' + api_path + \
- # Autotools paths
- ' -I' + common.build_path('DerivedSources', 'webkit2gtk', 'include') + \
- ' -I' + common.build_path('DerivedSources', 'WebKit2', 'webkit2gtk') + \
- # CMake paths
- ' -I' + common.build_path('DerivedSources', 'ForwardingHeaders', 'webkit2gtk') + \
- ' -I' + common.build_path('DerivedSources', 'webkit2gtk'),
- 'cross_reference_deps' : get_gtkdoc_module_paths(xref_deps) + [webkitdom_docs_html_path()],
- 'ignored_files': glob.glob(src_path('*Private.h')) + \
- glob.glob(os.path.join(injected_bundle_api_path, '*Private.h')) + \
- glob.glob(src_path('*Client*')) + \
- glob.glob(src_path('WebKitAuthenticationDialog.*')) + \
- glob.glob(src_path('WebKitBatteryProvider.*')) + \
- glob.glob(src_path('WebKitGeolocationProvider.*')) + \
- glob.glob(src_path('WebKitTextChecker.*')) + \
- glob.glob(src_path('WebKitWebViewBaseAccessible.*')) + \
- glob.glob(src_path('WebViewBaseInputMethodFilter.*')) + \
- glob.glob(os.path.join(generated_api_path, 'WebKitMarshal.*')) + \
- glob.glob(os.path.join(generated_api_path, 'WebKitEnumTypes.*')) + \
- glob.glob(src_path('tests/*.h'))
- }
- return options
+def files_to_ignore(source_dirs, headers_with_gtkdoc):
+ """
+ Find files to ignore during documentation generation. We assume that if an
+ implementation file exists for a header with gtkdoc (say webkitfoo.cpp for
+ webkitfoo.h) we shouldn't ignore that file. Currently this holds true for all
+ of the WebKit project.
+ """
+ implementation_files = list(headers_with_gtkdoc)
+ for header in headers_with_gtkdoc:
+ def add_file_if_exists(file):
+ if os.path.isfile(file):
+ implementation_files.append(os.path.abspath(file))
+ header_name_without_extension = os.path.splitext(header)[0]
+ add_file_if_exists(header_name_without_extension + ".cpp")
+ add_file_if_exists(header_name_without_extension + ".c")
-def get_webkit1_options(gtk_version, virtual_root):
- def src_path(*args):
- return jhbuildrc_common.top_level_path(*(('Source', 'WebKit', 'gtk') + args))
+ def file_should_be_ignored(file):
+ if os.path.splitext(file)[1] not in ['.h', '.c', '.cpp', '.cc']:
+ return False # These files are ignored anyway.
+ if not os.path.isfile(file):
+ return False
+ return os.path.abspath(file) not in implementation_files
- def webkitversionh_path():
- if common.is_cmake_build():
- return common.build_path('DerivedSources', 'webkitgtk')
- else:
- return common.build_path('Source', 'WebKit', 'gtk', 'webkit')
+ all_files = sum([[os.path.join(dir, file) for file in os.listdir(dir)] for dir in source_dirs], [])
+ return filter(file_should_be_ignored, all_files)
- xref_deps = get_common_xref_deps().copy()
- if gtk_version == 3:
- xref_deps.update({
- 'gtk+-3.0' : ['gtk3', 'gdk3']
- })
- else:
- xref_deps.update({
- 'gtk+-2.0' : ['gtk', 'gdk']
- })
+def get_generator_for_config(config_file, virtual_root):
+ if not os.path.isfile(config_file):
+ return None
- options = {
- 'decorator': 'WEBKIT_API|WEBKIT_DEPRECATED|WEBKIT_DEPRECATED_FOR\(.+\)',
- 'deprecation_guard': 'WEBKIT_DISABLE_DEPRECATED',
- 'library_path' : common.library_build_path(),
- 'virtual_root' : virtual_root,
- 'module_name' : 'webkitgtk',
- 'namespace' : 'webkit',
- 'doc_dir' : src_path('docs'),
- 'output_dir' : common.build_path('Documentation', 'webkitgtk'),
- 'source_dirs' : [src_path('webkit'), webkitversionh_path()],
- 'cflags' : ' -I' + common.build_path('WebKit', 'gtk') + \
- ' -I' + common.build_path('DerivedSources') + \
- ' -I' + src_path() + \
- ' -I' + jhbuildrc_common.top_level_path('Source') + \
- ' -I' + jhbuildrc_common.top_level_path('Source', '_javascript_Core', 'ForwardingHeaders'),
- 'cross_reference_deps' : get_gtkdoc_module_paths(xref_deps) + [webkitdom_docs_html_path()],
- 'ignored_files': glob.glob(src_path('webkit', '*private.*')) + \
- glob.glob(src_path('webkit', 'webkitauthenticationdialog.*')) + \
- glob.glob(src_path('webkit', 'webkitspellcheckerenchant.*'))
- }
- return options
+ config = SafeConfigParser()
+ config.read(config_file)
+ module_name = config.sections()[0]
+ pkgconfig_file = config.get(module_name, 'pkgconfig_file')
+ gtk_version = common.gtk_version_of_pkg_config_file(pkgconfig_file)
-def get_webkitdom_options(virtual_root):
- def derived_sources_path(*args):
- return common.build_path(*(('DerivedSources', 'webkitdom') + args))
- def src_path(*args):
- return jhbuildrc_common.top_level_path(*(('Source', 'WebCore', 'bindings', 'gobject') + args))
-
- xref_deps = { 'glib-2.0' : ['glib', 'gobject', 'gio'] }
-
- options = {
+ source_dirs = config.get(module_name, 'source_dirs').replace(';', ' ').split()
+ headers = [os.path.abspath(f) for f in config.get(module_name, 'headers').replace(';', ' ').split()]
+ return gtkdoc.PkgConfigGTKDoc(pkgconfig_file, {
'decorator': 'WEBKIT_API|WEBKIT_DEPRECATED|WEBKIT_DEPRECATED_FOR\(.+\)',
'deprecation_guard': 'WEBKIT_DISABLE_DEPRECATED',
- 'library_path' : common.library_build_path(),
- 'virtual_root' : virtual_root,
- 'module_name' : 'webkitdomgtk',
- 'namespace' : 'webkit_dom',
- 'doc_dir' : derived_sources_path('docs'),
- 'output_dir' : common.build_path('Documentation', 'webkitdomgtk'),
- 'source_dirs' : [derived_sources_path()],
- 'cflags' : ' -I' + derived_sources_path() + \
- ' -I' + src_path() + \
- ' -I' + jhbuildrc_common.top_level_path('Source'),
- 'cross_reference_deps' : get_gtkdoc_module_paths(xref_deps),
- 'ignored_files': glob.glob(derived_sources_path('*Private.h'))
- }
- return options
+ 'library_path': common.library_build_path(),
+ 'virtual_root': virtual_root,
+ 'module_name': module_name,
+ 'namespace': config.get(module_name, 'namespace'),
+ 'doc_dir': config.get(module_name, 'doc_dir'),
+ 'output_dir': common.build_path('Documentation', module_name),
+ 'source_dirs': source_dirs,
+ 'headers': headers,
+ 'cflags': " ".join(config.get(module_name, 'cflags').split()),
+ 'cross_reference_deps': get_gtkdoc_module_paths(gtk_version),
+ 'ignored_files': files_to_ignore(source_dirs, headers),
+ })
-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, skip_html):
+ print("\nGenerating {0} documentation...".format(generator.module_name))
generator.generate(not skip_html)
if generator.saw_warnings:
print_missing_api(generator)
return generator.saw_warnings
-if __name__ == "__main__":
- parser = argparse.ArgumentParser(description='Generate gtkdoc for WebKit.')
- parser.add_argument('-v', '--verbose', action='',
- help='Whether or not to run in verbose mode.')
- parser.add_argument('--rebase', action='',
- help='When specified, run the tool in rebase mode.')
- parser.add_argument('--skip-html', action='',
- help='Whether or not to skip HTML generation, which can be slow.')
- parser.add_argument('--virtual-root', type=str, default='',
- help='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 rebase_doc(generator):
+ print("\nRebasing {0} documentation...".format(generator.module_name))
+ try:
+ generator.rebase_installed_docs()
+ except Exception:
+ print("Rebase did not happen, likely no documentation is present.")
- arguments = parser.parse_args()
- configure_logging(arguments.verbose)
+def generate_documentation_for_config(config_file):
+ generator = get_generator_for_config(config_file, arguments.virtual_root)
+ if not generator:
+ print("{0} does not exist! Skipping that documentation.".format(os.path.basename(config_file)))
+ return
+ if not arguments.rebase:
+ generate_doc(generator, arguments.skip_html)
+ else:
+ rebase_doc(generator)
+ return generator.saw_warnings
+
+def prepare_environment_for_gtkdoc_generation():
# We need to add the _javascript_Core build directory to the PKG_CONFIG_PATH
# so that pkgconfig can properly resolve the libjavascriptcore dependency.
pkg_config_path = os.environ.get("PKG_CONFIG_PATH")
@@ -233,59 +169,31 @@
if os.environ.get('CC') == "clang":
os.environ['CFLAGS'] += ' -Qunused-arguments'
- saw_webkit1_warnings = saw_webkit2_warnings = False
- wk2_pkg_config_path = common.build_path('Source', 'WebKit2', 'webkit2gtk-3.0.pc')
- wk1_pkg_config_path = common.build_path('Source', 'WebKit', 'gtk', 'webkitgtk-3.0.pc')
- if not os.path.exists(wk1_pkg_config_path):
- wk1_pkg_config_path = common.build_path('Source', 'WebKit', 'gtk', 'webkit-1.0.pc')
+ # Paths from the GNUmakefile generated configuration files are relative to the build directory.
+ os.chdir(common.build_path())
- if os.path.exists(wk2_pkg_config_path):
- pkg_config_path = wk2_pkg_config_path
- elif os.path.exists(wk1_pkg_config_path):
- pkg_config_path = wk1_pkg_config_path
+if __name__ == "__main__":
+ parser = argparse.ArgumentParser(description='Generate gtkdoc for WebKit.')
+ parser.add_argument('-v', '--verbose', action='',
+ help='Whether or not to run in verbose mode.')
+ parser.add_argument('--rebase', action='',
+ help='When specified, run the tool in rebase mode.')
+ parser.add_argument('--skip-html', action='',
+ help='Whether or not to skip HTML generation, which can be slow.')
+ parser.add_argument('--virtual-root', type=str, default='',
+ help='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.')
- webkitdom_docs_path = common.build_path('DerivedSources', 'webkitdom', 'docs')
- if not common.is_cmake_build():
- generator = gtkdoc.PkgConfigGTKDoc(pkg_config_path, get_webkitdom_options(arguments.virtual_root))
- if not arguments.rebase:
- print("\nGenerating WebKitDOM documentation...")
- saw_webkitdom_warnings = generate_doc(generator, arguments.skip_html)
- else:
- print("\nRebasing WebKitDOM documentation...")
- try:
- generator.rebase_installed_docs()
- except Exception:
- print("Rebase did not happen, likely no documentation is present.")
+ arguments = parser.parse_args()
+ configure_logging(arguments.verbose)
- pkg_config_path = wk1_pkg_config_path
- if os.path.exists(pkg_config_path):
- options = get_webkit1_options(common.gtk_version_of_pkg_config_file(pkg_config_path), arguments.virtual_root)
- generator = gtkdoc.PkgConfigGTKDoc(pkg_config_path, options)
- if not arguments.rebase:
- print("Generating WebKit1 documentation...")
- saw_webkit1_warnings = generate_doc(generator, arguments.skip_html)
- else:
- print("Rebasing WebKit1 documentation...")
- try:
- generator.rebase_installed_docs()
- except Exception:
- print("Rebase did not happen, likely no documentation is present.")
+ prepare_environment_for_gtkdoc_generation()
- # WebKit2 might not be enabled, so check for the pkg-config file before building documentation.
- pkg_config_path = wk2_pkg_config_path
- if os.path.exists(pkg_config_path):
- generator = gtkdoc.PkgConfigGTKDoc(pkg_config_path, get_webkit2_options(arguments.virtual_root))
- if not arguments.rebase:
- print("\nGenerating WebKit2 documentation...")
- saw_webkit2_warnings = generate_doc(generator, arguments.skip_html)
- else:
- print("\nRebasing WebKit2 documentation...")
- try:
- generator.rebase_installed_docs()
- except Exception:
- print("Rebase did not happen, likely no documentation is present.")
-
- # For CMake we are still generating warnings because we lack DOM bindings docs,
- # so do not cause the build to fail for now.
+ saw_webkit1_warnings = generate_documentation_for_config(common.build_path('gtkdoc-webkitgtk.cfg'))
+ saw_webkit2_warnings = generate_documentation_for_config(common.build_path('gtkdoc-webkit2gtk.cfg'))
if not common.is_cmake_build():
- sys.exit(saw_webkit1_warnings or saw_webkit2_warnings)
+ generate_documentation_for_config(common.build_path('gtkdoc-webkitdom.cfg'))
+
+ sys.exit(saw_webkit1_warnings or saw_webkit2_warnings)
Modified: releases/WebKitGTK/webkit-2.4/Tools/gtk/gtkdoc.py (168708 => 168709)
--- releases/WebKitGTK/webkit-2.4/Tools/gtk/gtkdoc.py 2014-05-13 19:28:38 UTC (rev 168708)
+++ releases/WebKitGTK/webkit-2.4/Tools/gtk/gtkdoc.py 2014-05-13 19:29:03 UTC (rev 168709)
@@ -38,11 +38,14 @@
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 the source code to be scanned. Required.
+ 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.
@@ -87,6 +90,7 @@
# Parameters specific to scanning.
self.module_name = ''
self.source_dirs = []
+ self.headers = []
self.ignored_files = []
self.namespace = ''
self.decorator = ''
@@ -112,18 +116,18 @@
for key, value in iter(args.items()):
setattr(self, key, value)
- def raise_error_if_not_specified(key):
- if not getattr(self, key):
- raise Exception('%s not specified.' % key)
+ 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)
- raise_error_if_not_specified('output_dir')
- raise_error_if_not_specified('source_dirs')
- raise_error_if_not_specified('module_name')
-
# 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)
@@ -274,8 +278,9 @@
'--module=%s' % self.module_name,
'--rebuild-types']
- # Each source directory should be have its own "--source-dir=" prefix.
- args.extend(['--source-dir=%s' % path for path in self.source_dirs])
+ 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)
@@ -284,13 +289,18 @@
if self.output_dir:
args.append('--output-dir=%s' % self.output_dir)
- # 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)
+ # 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):
_______________________________________________ webkit-changes mailing list webkit-changes@lists.webkit.org https://lists.webkit.org/mailman/listinfo/webkit-changes
