Changeset 164632 in webkit


Ignore:
Timestamp:
Feb 24, 2014 11:30:21 PM (10 years ago)
Author:
Martin Robinson
Message:

[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.

Location:
trunk
Files:
16 edited

Legend:

Unmodified
Added
Removed

  • trunk/ChangeLog

    r164353 r164632  
     12014-02-24  Martin Robinson  <mrobinson@igalia.com>
     2
     3        [GTK] generate-gtkdoc should not generate documentation for source files for unbuilt source files
     4        https://bugs.webkit.org/show_bug.cgi?id=128417
     5
     6        Reviewed by Carlos Garcia Campos.
     7
     8        * Source/cmake/OptionsGTK.cmake: Define the paths to the pkgconfig files here, so that they
     9        may one day be used in the webkitdom config file generation.
     10
    1112014-02-18  Gyuyoung Kim  <gyuyoung.kim@samsung.com>
    212

  • trunk/GNUmakefile.am

    r163960 r164632  
    134134endif
    135135
     136webkit1_pkg_config_file = Source/WebKit/gtk/webkitgtk-@WEBKITGTK_API_MAJOR_VERSION@.@WEBKITGTK_API_MINOR_VERSION@.pc
     137webkit2_pkg_config_file = Source/WebKit2/webkit2gtk-@WEBKITGTK_API_MAJOR_VERSION@.@WEBKITGTK_API_MINOR_VERSION@.pc
     138
     139if ENABLE_WEBKIT2
     140webkitdom_pkgconfig_file = $(webkit2_pkg_config_file)
     141else
     142webkitdom_pkgconfig_file = $(webkit1_pkg_config_file)
     143endif
     144
    136145# We do not care at all about this implicit built-in make rules,
    137146# disable them to save some build time

  • trunk/Source/WebCore/ChangeLog

    r164627 r164632  
     12014-02-24  Martin Robinson  <mrobinson@igalia.com>
     2
     3        [GTK] generate-gtkdoc should not generate documentation for source files for unbuilt source files
     4        https://bugs.webkit.org/show_bug.cgi?id=128417
     5
     6        Reviewed by Carlos Garcia Campos.
     7
     8        * bindings/gobject/GNUmakefile.am: Generate a config file for webkitdom documentation generation.
     9
    1102014-02-24  Mark Lam  <mark.lam@apple.com>
    211

  • trunk/Source/WebCore/bindings/gobject/GNUmakefile.am

    r164131 r164632  
    576576        $(global_cflags)
    577577
     578webkitgtk_gdom_include_dirs = \
     579        -I$(WebCore)/bindings \
     580        -I$(WebCore)/bindings/gobject \
     581        -I$(GENSOURCES_WEBKITDOM)
     582
    578583libGObjectDOMBindings_la_CPPFLAGS = \
    579584        -DBUILDING_WebCore \
    580585        -DBUILDING_WEBKIT \
    581         -I$(WebCore)/bindings \
    582         -I$(WebCore)/bindings/gobject \
    583         -I$(GENSOURCES_WEBKITDOM) \
     586        $(webkitgtk_gdom_include_dirs) \
    584587        $(global_cppflags) \
    585588        $(platform_cppflags) \
    … …  
    592595        $(GLIB_CFLAGS) \
    593596        $(LIBSOUP_CFLAGS)
     597
     598gtkdoc-webkitdom.cfg: $(WebCore)/bindings/gobject/GNUmakefile.am $(srcdir)/Tools/gtk/GNUmakefile.am
     599        $(AM_V_GEN)echo "[webkitdomgtk]" > $@ && \
     600        echo "pkgconfig_file=$(webkitdom_pkgconfig_file)" >> $@ && \
     601        echo "namespace=webkit_dom" >> $@ && \
     602        echo "doc_dir=DerivedSources/webkitdom/docs" >> $@ && \
     603        echo -e "cflags=-I$(srcdir)/Source $(webkitgtk_gdom_include_dirs)" >> $@ && \
     604        echo "source_dirs=$(top_builddir)/DerivedSources/webkitdom $(srcdir)/Source/WebCore/bindings/gobject" >> $@ && \
     605        echo "headers=$(webkitgtk_gdom_built_h_api) DerivedSources/webkitdom/WebKitDOMDeprecated.h" >> $@
     606BUILT_SOURCES += gtkdoc-webkitdom.cfg

  • trunk/Source/WebKit/ChangeLog

    r164618 r164632  
     12014-02-24  Martin Robinson  <mrobinson@igalia.com>
     2
     3        [GTK] generate-gtkdoc should not generate documentation for source files for unbuilt source files
     4        https://bugs.webkit.org/show_bug.cgi?id=128417
     5
     6        Reviewed by Carlos Garcia Campos.
     7
     8        * PlatformGTK.cmake: Correct the definition of WebKitGTK_ENUM_GENERATION_HEADERS and generate
     9        a gtkdoc-webkitgtk.cfg file to be used by generate-gtkdoc.
     10
    1112014-02-24  Anders Carlsson  <andersca@apple.com>
    212

  • trunk/Source/WebKit/PlatformGTK.cmake

    r164438 r164632  
    22file(MAKE_DIRECTORY ${DERIVED_SOURCES_WEBKITGTK_API_DIR})
    33configure_file(gtk/webkit/webkitversion.h.in ${DERIVED_SOURCES_WEBKITGTK_API_DIR}/webkitversion.h)
    4 configure_file(gtk/webkit.pc.in ${CMAKE_BINARY_DIR}/Source/WebKit/gtk/webkitgtk-${WEBKITGTK_API_VERSION}.pc @ONLY)
     4configure_file(gtk/webkit.pc.in ${WebKit_PKGCONFIG_FILE} @ONLY)
    55
    66add_definitions(-DPACKAGE_LOCALE_DIR="${CMAKE_INSTALL_FULL_LOCALEDIR}")
    … …  
    156156# To generate webkitenumtypes.h we want to use all installed headers, except webkitenumtypes.h itself.
    157157set(WebKitGTK_ENUM_GENERATION_HEADERS ${WebKitGTK_INSTALLED_HEADERS})
    158 list(REMOVE_ITEM WebKitGTK_ENUM_GENERATION_HEADERS ${DERIVED_SOURCES_WEBKIT2GTK_API_DIR}/webkitenumtypes.h)
     158list(REMOVE_ITEM WebKitGTK_ENUM_GENERATION_HEADERS ${DERIVED_SOURCES_WEBKITGTK_API_DIR}/webkitenumtypes.h)
    159159add_custom_command(
    160160    OUTPUT ${DERIVED_SOURCES_WEBKITGTK_API_DIR}/webkitenumtypes.h
    … …  
    229229        DESTINATION ${INTROSPECTION_INSTALL_TYPELIBDIR}
    230230)
     231
     232file(WRITE ${CMAKE_BINARY_DIR}/gtkdoc-webkitgtk.cfg
     233    "[webkitgtk]\n"
     234    "pkgconfig_file=${WebKit_PKGCONFIG_FILE}\n"
     235    "namespace=webkit\n"
     236    "cflags=-I${DERIVED_SOURCES_DIR}\n"
     237    "       -I${CMAKE_SOURCE_DIR}\n"
     238    "       -I${CMAKE_SOURCE_DIR}/Source\n"
     239    "       -I${CMAKE_SOURCE_DIR}/JavaScriptCore/ForwardingHeaders\n"
     240    "doc_dir=${WEBKIT_DIR}/gtk/docs\n"
     241    "source_dirs=${WEBKIT_DIR}/gtk/webkit\n"
     242    "            ${DERIVED_SOURCES_WEBKITGTK_API_DIR}\n"
     243    "headers=${WebKitGTK_ENUM_GENERATION_HEADERS}\n"
     244)

  • trunk/Source/WebKit/gtk/ChangeLog

    r164596 r164632  
     12014-02-24  Martin Robinson  <mrobinson@igalia.com>
     2
     3        [GTK] generate-gtkdoc should not generate documentation for source files for unbuilt source files
     4        https://bugs.webkit.org/show_bug.cgi?id=128417
     5
     6        Reviewed by Carlos Garcia Campos.
     7
     8        * GNUmakefile.am: Generate a config file for generate-gtkdoc.
     9
    1102014-02-24  Enrique Ocaña González  <eocanha@igalia.com>
    211

  • trunk/Source/WebKit/gtk/GNUmakefile.am

    r164438 r164632  
    377377        && rm -f xgen-gtc
    378378
     379gtkdoc-webkitgtk.cfg: $(WebKit)/GNUmakefile.am $(srcdir)/Tools/gtk/GNUmakefile.am
     380        $(AM_V_GEN)echo "[webkitgtk]" > $@ && \
     381        echo "pkgconfig_file=$(webkit1_pkg_config_file)" >> $@ && \
     382        echo "namespace=webkit" >> $@ && \
     383        echo -e "cflags=$(libwebkitgtk_@WEBKITGTK_API_MAJOR_VERSION@_@WEBKITGTK_API_MINOR_VERSION@_la_CPPFLAGS)" >> $@ && \
     384        echo "doc_dir=$(srcdir)/Source/WebKit/gtk/docs" >> $@ && \
     385        echo -e "source_dirs=$(srcdir)/Source/WebKit/gtk/webkit\n \
     386           Source/WebKit/gtk/webkit" >> $@ && \
     387        echo -e "headers=$(webkitgtk_static_h_api) Source/WebKit/gtk/webkit/webkitversion.h" >> $@
     388BUILT_SOURCES += gtkdoc-webkitgtk.cfg
     389
    379390EXTRA_DIST += \
    380391        $(WebKit)/ChangeLog \

  • trunk/Source/WebKit2/ChangeLog

    r164628 r164632  
     12014-02-24  Martin Robinson  <mrobinson@igalia.com>
     2
     3        [GTK] generate-gtkdoc should not generate documentation for source files for unbuilt source files
     4        https://bugs.webkit.org/show_bug.cgi?id=128417
     5
     6        Reviewed by Carlos Garcia Campos.
     7
     8        * GNUmakefile.am: Generate a config file for generate-gtkdoc.
     9        * PlatformGTK.cmake: Ditto.
     10
    1112014-02-24  Dan Bernstein  <mitz@apple.com>
    212

  • trunk/Source/WebKit2/GNUmakefile.am

    r163956 r164632  
    804804        $(global_cxxflags)
    805805
     806# It would be nice to use the CPPFLAGS from the WebKit2 library here, but the prefix
     807# header doesn't seem to play nicely with the gtkdoc tools.
     808gtkdoc-webkit2gtk.cfg: $(WebKit2)/GNUmakefile.am $(WebKit2)/GNUmakefile.list.am
     809        $(AM_V_GEN)echo "[webkit2gtk]" > $@ && \
     810        echo "pkgconfig_file=$(webkit2_pkg_config_file)" >> $@ && \
     811        echo "namespace=webkit" >> $@ && \
     812        echo -e "cflags=-I$(srcdir)/Source\n \
     813       -I$(WebKit2)/UIProcess/API/gtk\n \
     814       -IDerivedSources/webkit2gtk/include\n \
     815       -IDerivedSources/WebKit2/webkit2gtk\n" >> $@ && \
     816        echo "doc_dir=$(WebKit2)/UIProcess/API/gtk/docs" >> $@ && \
     817        echo -e "source_dirs=$(WebKit2)/UIProcess/API/gtk\n \
     818           $(WebKit2)/WebProcess/InjectedBundle/API/gtk\n \
     819           DerivedSources/WebKit2/webkit2gtk/webkit2\n" >> $@ && \
     820        echo -e "headers=$(webkit2gtk_ui_h_api)\n \
     821         $(webkit2gtk_web_extension_h_api)\n \
     822         DerivedSources/WebKit2/webkit2gtk/webkit2/WebKitVersion.h" >> $@
     823BUILT_SOURCES += gtkdoc-webkit2gtk.cfg
     824
    806825EXTRA_DIST += \
    807826        $(WebKit2)/UIProcess/API/gtk/docs/webkit2gtk-docs.sgml \

  • trunk/Source/WebKit2/PlatformGTK.cmake

    r164562 r164632  
    55
    66configure_file(UIProcess/API/gtk/WebKitVersion.h.in ${DERIVED_SOURCES_WEBKIT2GTK_API_DIR}/WebKitVersion.h)
    7 configure_file(webkit2gtk.pc.in ${CMAKE_BINARY_DIR}/Source/WebKit2/webkit2gtk-${WEBKITGTK_API_VERSION}.pc @ONLY)
     7configure_file(webkit2gtk.pc.in ${WebKit2_PKGCONFIG_FILE} @ONLY)
    88
    99add_definitions(-DWEBKIT2_COMPILATION)
    … …  
    791791        DESTINATION ${INTROSPECTION_INSTALL_TYPELIBDIR}
    792792)
     793
     794file(WRITE ${CMAKE_BINARY_DIR}/gtkdoc-webkit2gtk.cfg
     795    "[webkit2gtk]\n"
     796    "pkgconfig_file=${WebKit2_PKGCONFIG_FILE}\n"
     797    "namespace=webkit\n"
     798    "cflags=-I${CMAKE_SOURCE_DIR}/Source\n"
     799    "       -I${WEBKIT2_DIR}/UIProcess/API/gtk\n"
     800    "       -I${DERIVED_SOURCES_WEBKIT2GTK_DIR}\n"
     801    "       -I${FORWARDING_HEADERS_WEBKIT2GTK_DIR}\n"
     802    "doc_dir=${WEBKIT2_DIR}/UIProcess/API/gtk/docs\n"
     803    "source_dirs=${WEBKIT2_DIR}/UIProcess/API/gtk\n"
     804    "            ${WEBKIT2_DIR}/WebProcess/InjectedBundle/API/gtk\n"
     805    "            ${DERIVED_SOURCES_WEBKIT2GTK_API_DIR}\n"
     806    "headers=${WebKit2GTK_ENUM_GENERATION_HEADERS} ${WebKit2WebExtension_INSTALLED_HEADERS}\n"
     807)

  • trunk/Source/cmake/OptionsGTK.cmake

    r164257 r164632  
    265265set(FORWARDING_HEADERS_WEBKIT2GTK_DIR ${FORWARDING_HEADERS_DIR}/webkit2gtk)
    266266set(FORWARDING_HEADERS_WEBKIT2GTK_EXTENSION_DIR ${FORWARDING_HEADERS_DIR}/webkit2gtk-webextension)
     267
     268set(WebKit_PKGCONFIG_FILE ${CMAKE_BINARY_DIR}/Source/WebKit/gtk/webkitgtk-${WEBKITGTK_API_VERSION}.pc)
     269set(WebKit2_PKGCONFIG_FILE ${CMAKE_BINARY_DIR}/Source/WebKit2/webkit2gtk-${WEBKITGTK_API_VERSION}.pc)
     270
    267271set(SHOULD_INSTALL_JS_SHELL ON)
    268272

  • trunk/Tools/ChangeLog

    r164624 r164632  
     12014-02-24  Martin Robinson  <mrobinson@igalia.com>
     2
     3        [GTK] generate-gtkdoc should not generate documentation for source files for unbuilt source files
     4        https://bugs.webkit.org/show_bug.cgi?id=128417
     5
     6        Reviewed by Carlos Garcia Campos.
     7
     8        * gtk/GNUmakefile.am: Make the documentation process depend on the configuration files.
     9        * gtk/generate-gtkdoc: Switch from using hard-coded configurations to reading them from
     10        a makefile. This allows accepting a header list from the build system, which can be used
     11        to dynamically build a list of ignored files. We can ignore any source file that doesn't
     12        have a corresponding header file on the header list.
     13        * gtk/gtkdoc.py: Now accept a headers parameter, which can be used instead of passing just
     14        source directories to gtkdoc-scan.
     15
    1162014-02-24  Anders Carlsson  <andersca@apple.com>
    217

  • trunk/Tools/gtk/GNUmakefile.am

    r161816 r164632  
    1111DISTCLEANFILES += docs-build.stamp
    1212
    13 docs_build_stamp_list = \
     13docs_build_dependencies = \
    1414        Source/WebKit/gtk/docs/webkitenvironment.xml
    1515
    1616if ENABLE_WEBKIT1
    17 docs_build_stamp_list += \
     17docs_build_dependencies += \
    1818        libwebkitgtk-@WEBKITGTK_API_MAJOR_VERSION@.@WEBKITGTK_API_MINOR_VERSION@.la \
    1919        Source/WebKit/gtk/docs/webkitgtk-docs.sgml \
    20         Source/WebKit/gtk/docs/webkitgtk-sections.txt
     20        Source/WebKit/gtk/docs/webkitgtk-sections.txt \
     21        gtkdoc-webkitgtk.cfg
    2122endif
    2223
    2324if ENABLE_WEBKIT2
    24 docs_build_stamp_list += \
     25docs_build_dependencies += \
    2526        libwebkit2gtk-@WEBKITGTK_API_MAJOR_VERSION@.@WEBKITGTK_API_MINOR_VERSION@.la \
    2627        Source/WebKit2/UIProcess/API/gtk/docs/webkit2gtk-docs.sgml \
    27         Source/WebKit2/UIProcess/API/gtk/docs/webkit2gtk-sections.txt
     28        Source/WebKit2/UIProcess/API/gtk/docs/webkit2gtk-sections.txt \
     29        gtkdoc-webkit2gtk.cfg
    2830endif
    2931
    … …  
    4042        $(top_builddir)/DerivedSources/webkitdom/docs/webkitdomgtk-sections.txt
    4143
    42 docs_build_stamp_list += \
     44docs_build_dependencies += \
    4345        libGObjectDOMBindings.la \
    4446        $(top_builddir)/DerivedSources/webkitdom/docs/webkitdomgtk-docs.sgml \
    45         $(top_builddir)/DerivedSources/webkitdom/docs/webkitdomgtk-sections.txt
     47        $(top_builddir)/DerivedSources/webkitdom/docs/webkitdomgtk-sections.txt \
     48        gtkdoc-webkitdom.cfg
    4649
    47 docs-build.stamp: $(docs_build_stamp_list)
     50docs-build.stamp: $(docs_build_dependencies)
    4851        CC=$(CC) $(srcdir)/Tools/gtk/generate-gtkdoc
    4952        @touch docs-build.stamp

  • trunk/Tools/gtk/generate-gtkdoc

    r164585 r164632  
    1616# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
    1717
     18from __future__ import print_function
     19from ConfigParser import SafeConfigParser
     20
    1821import argparse
    1922import common
    … …  
    2326import os.path
    2427import sys
    25 
    26 sys.path.insert(0, os.path.join(os.path.dirname(__file__), "../jhbuild"))
    27 import jhbuildrc_common
    2828
    2929def configure_logging(verbose):
    … …  
    3939        handler.setFormatter(logging.Formatter('%(message)s'))
    4040
    41 
    42 def get_gtkdoc_module_paths(xref_dep_packages):
    43     deps = []
    44     html_dir = os.path.join('share', 'gtk-doc', 'html')
    45 
    46     for package in xref_dep_packages:
    47         prefix = common.prefix_of_pkg_config_file(package)
    48         if prefix is None:
    49             continue
    50         for module in xref_dep_packages[package]:
    51             deps.append(os.path.join(prefix, html_dir, module))
    52 
    53     return deps
    54 
    55 
    56 def get_common_xref_deps():
    57     return {
     41def get_gtkdoc_module_paths(gtk_version):
     42    dependent_packages = {
    5843        'glib-2.0' : ['glib', 'gobject', 'gio'],
    5944        'libsoup-2.4' : ['libsoup-2.4'],
    6045        'gdk-pixbuf-2.0': ['gdk-pixbuf']
    6146    }
     47    if gtk_version == 3:
     48        dependent_packages.update({'gtk+-3.0' : ['gtk3', 'gdk3']})
     49    else:
     50        dependent_packages.update({'gtk+-2.0' : ['gtk', 'gdk']})
    6251
    63 def webkitdom_docs_html_path():
    64     return common.build_path('Documentation', 'webkitdomgtk', 'html')
    65 
    66 def get_webkit2_options(virtual_root):
    67     api_path = jhbuildrc_common.top_level_path('Source', 'WebKit2', 'UIProcess', 'API', 'gtk')
    68     injected_bundle_api_path = jhbuildrc_common.top_level_path('Source', 'WebKit2', 'WebProcess', 'InjectedBundle', 'API', 'gtk')
    69 
    70     if common.is_cmake_build():
    71         generated_api_path = common.build_path('DerivedSources', 'webkit2gtk', 'webkit2')
    72     else:
    73         generated_api_path = common.build_path('DerivedSources', 'WebKit2', 'webkit2gtk', 'webkit2')
    74 
    75     xref_deps = get_common_xref_deps().copy()
    76     xref_deps.update({
    77         'gtk+-3.0' : ['gtk3', 'gdk3']
    78     })
    79 
    80     def src_path(*args):
    81         return os.path.join(api_path, *args)
    82 
    83     options = {
    84         'decorator': 'WEBKIT_API|WEBKIT_DEPRECATED|WEBKIT_DEPRECATED_FOR\(.+\)',
    85         'deprecation_guard': 'WEBKIT_DISABLE_DEPRECATED',
    86         'library_path' : common.library_build_path(),
    87         'virtual_root' : virtual_root,
    88         'module_name' : 'webkit2gtk',
    89         'namespace' : 'webkit',
    90         'doc_dir' : src_path('docs'),
    91         'output_dir' : common.build_path('Documentation', 'webkit2gtk'),
    92         'source_dirs' : [src_path(), generated_api_path, injected_bundle_api_path],
    93         'cflags' :
    94             # Common paths
    95             ' -I' + jhbuildrc_common.top_level_path('Source') + \
    96             ' -I' + api_path + \
    97             # Autotools paths
    98             ' -I' + common.build_path('DerivedSources', 'webkit2gtk', 'include') + \
    99             ' -I' + common.build_path('DerivedSources', 'WebKit2', 'webkit2gtk') + \
    100             # CMake paths
    101             ' -I' + common.build_path('DerivedSources', 'ForwardingHeaders', 'webkit2gtk') + \
    102             ' -I' + common.build_path('DerivedSources', 'webkit2gtk'),
    103         'cross_reference_deps' : get_gtkdoc_module_paths(xref_deps) + [webkitdom_docs_html_path()],
    104         'ignored_files': glob.glob(src_path('*Private.h')) + \
    105                          glob.glob(os.path.join(injected_bundle_api_path, '*Private.h')) + \
    106                          glob.glob(src_path('*Client*')) + \
    107                          glob.glob(src_path('WebKitAuthenticationDialog.*')) + \
    108                          glob.glob(src_path('WebKitBatteryProvider.*')) + \
    109                          glob.glob(src_path('WebKitGeolocationProvider.*')) + \
    110                          glob.glob(src_path('WebKitTextChecker.*')) + \
    111                          glob.glob(src_path('WebKitWebViewBaseAccessible.*')) + \
    112                          glob.glob(src_path('WebViewBaseInputMethodFilter.*')) + \
    113                          glob.glob(os.path.join(generated_api_path, 'WebKitMarshal.*')) + \
    114                          glob.glob(os.path.join(generated_api_path, 'WebKitEnumTypes.*')) + \
    115                          glob.glob(src_path('tests/*.h'))
    116     }
    117     return options
    118 
    119 def get_webkit1_options(gtk_version, virtual_root):
    120     def src_path(*args):
    121         return jhbuildrc_common.top_level_path(*(('Source', 'WebKit', 'gtk') + args))
    122 
    123     def webkitversionh_path():
    124         if common.is_cmake_build():
    125             return common.build_path('DerivedSources', 'webkitgtk')
    126         else:
    127             return common.build_path('Source', 'WebKit', 'gtk', 'webkit')
    128 
    129     xref_deps = get_common_xref_deps().copy()
    130     if gtk_version == 3:
    131         xref_deps.update({
    132                 'gtk+-3.0' : ['gtk3', 'gdk3']
    133         })
    134     else:
    135         xref_deps.update({
    136                 'gtk+-2.0' : ['gtk', 'gdk']
    137         })
    138 
    139     options = {
    140         'decorator': 'WEBKIT_API|WEBKIT_DEPRECATED|WEBKIT_DEPRECATED_FOR\(.+\)',
    141         'deprecation_guard': 'WEBKIT_DISABLE_DEPRECATED',
    142         'library_path' : common.library_build_path(),
    143         'virtual_root' : virtual_root,
    144         'module_name' : 'webkitgtk',
    145         'namespace' : 'webkit',
    146         'doc_dir' : src_path('docs'),
    147         'output_dir' : common.build_path('Documentation', 'webkitgtk'),
    148         'source_dirs' : [src_path('webkit'), webkitversionh_path()],
    149         'cflags' : ' -I' + common.build_path('WebKit', 'gtk') + \
    150                    ' -I' + common.build_path('DerivedSources') + \
    151                    ' -I' + src_path() + \
    152                    ' -I' + jhbuildrc_common.top_level_path('Source') + \
    153                    ' -I' + jhbuildrc_common.top_level_path('Source', 'JavaScriptCore', 'ForwardingHeaders'),
    154         'cross_reference_deps' : get_gtkdoc_module_paths(xref_deps) + [webkitdom_docs_html_path()],
    155         'ignored_files': glob.glob(src_path('webkit', '*private.*')) + \
    156                          glob.glob(src_path('webkit', 'webkitauthenticationdialog.*')) + \
    157                          glob.glob(src_path('webkit', 'webkitspellcheckerenchant.*'))
    158     }
    159     return options
    160 
    161 def get_webkitdom_options(virtual_root):
    162     def derived_sources_path(*args):
    163         return common.build_path(*(('DerivedSources', 'webkitdom') + args))
    164     def src_path(*args):
    165         return jhbuildrc_common.top_level_path(*(('Source', 'WebCore', 'bindings', 'gobject') + args))
    166 
    167     xref_deps = { 'glib-2.0' : ['glib', 'gobject', 'gio'] }
    168 
    169     options = {
    170         'decorator': 'WEBKIT_API|WEBKIT_DEPRECATED|WEBKIT_DEPRECATED_FOR\(.+\)',
    171         'deprecation_guard': 'WEBKIT_DISABLE_DEPRECATED',
    172         'library_path' : common.library_build_path(),
    173         'virtual_root' : virtual_root,
    174         'module_name' : 'webkitdomgtk',
    175         'namespace' : 'webkit_dom',
    176         'doc_dir' : derived_sources_path('docs'),
    177         'output_dir' : common.build_path('Documentation', 'webkitdomgtk'),
    178         'source_dirs' : [derived_sources_path()],
    179         'cflags' : ' -I' + derived_sources_path() + \
    180                    ' -I' + src_path() + \
    181                    ' -I' + jhbuildrc_common.top_level_path('Source'),
    182         'cross_reference_deps' : get_gtkdoc_module_paths(xref_deps),
    183         'ignored_files': glob.glob(derived_sources_path('*Private.h'))
    184     }
    185     return options
     52    paths = []
     53    html_dir = os.path.join('share', 'gtk-doc', 'html')
     54    for package, modules in dependent_packages.iteritems():
     55        prefix = common.prefix_of_pkg_config_file(package)
     56        if prefix is None:
     57            continue
     58        for module in modules:
     59            paths.append(os.path.join(prefix, html_dir, module))
     60    # This technically is not needed for the GObject DOM bindings documentation itself,
     61    # but adding it doesn't hurt and allows us to avoid a check here.
     62    paths.append(common.build_path('Documentation', 'webkitdomgtk', 'html'))
     63    return paths
    18664
    18765def print_missing_api(generator):
    … …  
    19169    print("\nThe following API are missing documentation:")
    19270    for api in missing_api:
    193         print("\t%s" % api)
     71        print("\t{0}".format(api))
     72
     73def files_to_ignore(source_dirs, headers_with_gtkdoc):
     74    """
     75    Find files to ignore during documentation generation. We assume that if an
     76    implementation file exists for a header with gtkdoc (say webkitfoo.cpp for
     77    webkitfoo.h) we shouldn't ignore that file. Currently this holds true for all
     78    of the WebKit project.
     79    """
     80    implementation_files = list(headers_with_gtkdoc)
     81    for header in headers_with_gtkdoc:
     82        def add_file_if_exists(file):
     83            if os.path.isfile(file):
     84                implementation_files.append(os.path.abspath(file))
     85        header_name_without_extension = os.path.splitext(header)[0]
     86        add_file_if_exists(header_name_without_extension + ".cpp")
     87        add_file_if_exists(header_name_without_extension + ".c")
     88
     89    def file_should_be_ignored(file):
     90        if os.path.splitext(file)[1] not in ['.h', '.c', '.cpp', '.cc']:
     91            return False # These files are ignored anyway.
     92        if not os.path.isfile(file):
     93            return False
     94        return os.path.abspath(file) not in implementation_files
     95
     96    all_files = sum([[os.path.join(dir, file) for file in os.listdir(dir)] for dir in source_dirs], [])
     97    return filter(file_should_be_ignored, all_files)
     98
     99def get_generator_for_config(config_file, virtual_root):
     100    if not os.path.isfile(config_file):
     101        return None
     102
     103    config = SafeConfigParser()
     104    config.read(config_file)
     105    module_name = config.sections()[0]
     106    pkgconfig_file = config.get(module_name, 'pkgconfig_file')
     107    gtk_version = common.gtk_version_of_pkg_config_file(pkgconfig_file)
     108
     109    source_dirs = config.get(module_name, 'source_dirs').replace(';', ' ').split()
     110    headers = [os.path.abspath(f) for f in config.get(module_name, 'headers').replace(';', ' ').split()]
     111    return gtkdoc.PkgConfigGTKDoc(pkgconfig_file, {
     112        'decorator': 'WEBKIT_API|WEBKIT_DEPRECATED|WEBKIT_DEPRECATED_FOR\(.+\)',
     113        'deprecation_guard': 'WEBKIT_DISABLE_DEPRECATED',
     114        'library_path': common.library_build_path(),
     115        'virtual_root': virtual_root,
     116        'module_name': module_name,
     117        'namespace': config.get(module_name, 'namespace'),
     118        'doc_dir': config.get(module_name, 'doc_dir'),
     119        'output_dir': common.build_path('Documentation', module_name),
     120        'source_dirs': source_dirs,
     121        'headers': headers,
     122        'cflags': " ".join(config.get(module_name, 'cflags').split()),
     123        'cross_reference_deps': get_gtkdoc_module_paths(gtk_version),
     124        'ignored_files': files_to_ignore(source_dirs, headers),
     125    })
    194126
    195127def generate_doc(generator, skip_html):
     128    print("\nGenerating {0} documentation...".format(generator.module_name))
    196129    generator.generate(not skip_html)
    197130    if generator.saw_warnings:
    198131        print_missing_api(generator)
    199132    return generator.saw_warnings
     133
     134def rebase_doc(generator):
     135    print("\nRebasing {0} documentation...".format(generator.module_name))
     136    try:
     137        generator.rebase_installed_docs()
     138    except Exception:
     139        print("Rebase did not happen, likely no documentation is present.")
     140
     141def generate_documentation_for_config(config_file):
     142    generator = get_generator_for_config(config_file, arguments.virtual_root)
     143    if not generator:
     144        print("{0} does not exist! Skipping that documentation.".format(os.path.basename(config_file)))
     145        return
     146
     147    if not arguments.rebase:
     148        generate_doc(generator, arguments.skip_html)
     149    else:
     150        rebase_doc(generator)
     151    return generator.saw_warnings
     152
     153def prepare_environment_for_gtkdoc_generation():
     154    # We need to add the JavaScriptCore build directory to the PKG_CONFIG_PATH
     155    # so that pkgconfig can properly resolve the libjavascriptcore dependency.
     156    pkg_config_path = os.environ.get("PKG_CONFIG_PATH")
     157    os.environ['PKG_CONFIG_PATH'] = common.build_path('Source', 'JavaScriptCore')
     158    if pkg_config_path:
     159        os.environ['PKG_CONFIG_PATH'] += ':' + pkg_config_path
     160
     161    # Newer versions of glib have deprecated g_type_init, so we need to disable
     162    # that warning when running gtkdoc-scanobj by overriding the CFLAGS we use
     163    # to compile it.
     164    cflags = os.environ.get('CFLAGS', '')
     165    cflags += ' -DGLIB_VERSION_MIN_REQUIRED=GLIB_VERSION_2_32'
     166    os.environ['CFLAGS'] = cflags
     167
     168    # Clang can be noisy, throwing unnecessary warnings for unused arguments.
     169    if os.environ.get('CC') == "clang":
     170        os.environ['CFLAGS'] += ' -Qunused-arguments'
     171
     172    # Paths from the GNUmakefile generated configuration files are relative to the build directory.
     173    os.chdir(common.build_path())
    200174
    201175if __name__ == "__main__":
    … …  
    216190    configure_logging(arguments.verbose)
    217191
    218     # We need to add the JavaScriptCore build directory to the PKG_CONFIG_PATH
    219     # so that pkgconfig can properly resolve the libjavascriptcore dependency.
    220     pkg_config_path = os.environ.get("PKG_CONFIG_PATH")
    221     os.environ['PKG_CONFIG_PATH'] = common.build_path('Source', 'JavaScriptCore')
    222     if pkg_config_path:
    223         os.environ['PKG_CONFIG_PATH'] += ':' + pkg_config_path
     192    prepare_environment_for_gtkdoc_generation()
    224193
    225     # Newer versions of glib have deprecated g_type_init, so we need to disable
    226     # that warning when running gtkdoc-scanobj by overriding the CFLAGS we use
    227     # to compile it.
    228     cflags = os.environ.get('CFLAGS', '')
    229     cflags += ' -DGLIB_VERSION_MIN_REQUIRED=GLIB_VERSION_2_32'
    230     os.environ['CFLAGS'] = cflags
     194    saw_webkit1_warnings = generate_documentation_for_config(common.build_path('gtkdoc-webkitgtk.cfg'))
     195    saw_webkit2_warnings = generate_documentation_for_config(common.build_path('gtkdoc-webkit2gtk.cfg'))
     196    if not common.is_cmake_build():
     197        generate_documentation_for_config(common.build_path('gtkdoc-webkitdom.cfg'))
    231198
    232     # Clang can be noisy, throwing unnecessary warnings for unused arguments.
    233     if os.environ.get('CC') == "clang":
    234         os.environ['CFLAGS'] += ' -Qunused-arguments'
    235 
    236     saw_webkit1_warnings = saw_webkit2_warnings = False
    237     wk2_pkg_config_path = common.build_path('Source', 'WebKit2', 'webkit2gtk-3.0.pc')
    238     wk1_pkg_config_path = common.build_path('Source', 'WebKit', 'gtk', 'webkitgtk-3.0.pc')
    239     if not os.path.exists(wk1_pkg_config_path):
    240         wk1_pkg_config_path = common.build_path('Source', 'WebKit', 'gtk', 'webkit-1.0.pc')
    241 
    242     if os.path.exists(wk2_pkg_config_path):
    243         pkg_config_path = wk2_pkg_config_path
    244     elif os.path.exists(wk1_pkg_config_path):
    245         pkg_config_path = wk1_pkg_config_path
    246 
    247     webkitdom_docs_path = common.build_path('DerivedSources', 'webkitdom', 'docs')
    248     if not common.is_cmake_build():
    249         generator = gtkdoc.PkgConfigGTKDoc(pkg_config_path, get_webkitdom_options(arguments.virtual_root))
    250         if not arguments.rebase:
    251             print("\nGenerating WebKitDOM documentation...")
    252             saw_webkitdom_warnings = generate_doc(generator, arguments.skip_html)
    253         else:
    254             print("\nRebasing WebKitDOM documentation...")
    255             try:
    256                 generator.rebase_installed_docs()
    257             except Exception:
    258                 print("Rebase did not happen, likely no documentation is present.")
    259 
    260     pkg_config_path = wk1_pkg_config_path
    261     if os.path.exists(pkg_config_path):
    262         options = get_webkit1_options(common.gtk_version_of_pkg_config_file(pkg_config_path), arguments.virtual_root)
    263         generator = gtkdoc.PkgConfigGTKDoc(pkg_config_path, options)
    264         if not arguments.rebase:
    265             print("Generating WebKit1 documentation...")
    266             saw_webkit1_warnings = generate_doc(generator, arguments.skip_html)
    267         else:
    268             print("Rebasing WebKit1 documentation...")
    269             try:
    270                 generator.rebase_installed_docs()
    271             except Exception:
    272                 print("Rebase did not happen, likely no documentation is present.")
    273 
    274     # WebKit2 might not be enabled, so check for the pkg-config file before building documentation.
    275     pkg_config_path = wk2_pkg_config_path
    276     if os.path.exists(pkg_config_path):
    277         generator = gtkdoc.PkgConfigGTKDoc(pkg_config_path, get_webkit2_options(arguments.virtual_root))
    278         if not arguments.rebase:
    279             print("\nGenerating WebKit2 documentation...")
    280             saw_webkit2_warnings = generate_doc(generator, arguments.skip_html)
    281         else:
    282             print("\nRebasing WebKit2 documentation...")
    283             try:
    284                 generator.rebase_installed_docs()
    285             except Exception:
    286                 print("Rebase did not happen, likely no documentation is present.")
    287 
    288     # For CMake we are still generating warnings because we lack DOM bindings docs,
    289     # so do not cause the build to fail for now.
    290     if not common.is_cmake_build():
    291         sys.exit(saw_webkit1_warnings or saw_webkit2_warnings)
     199    sys.exit(saw_webkit1_warnings or saw_webkit2_warnings)

  • trunk/Tools/gtk/gtkdoc.py

    r158908 r164632  
    3939                          is typically the library name. Required if not library path
    4040                          is given.
    41     source_dirs        -- A list of paths to the source code to be scanned. Required.
     41    source_dirs        -- A list of paths to directories of source code to be scanned.
     42                          Required if headers is not specified.
    4243    ignored_files      -- A list of filenames to ignore in the source directory. It is
    4344                          only necessary to provide the basenames of these files.
    4445                          Typically it is important to provide an updated list of
    4546                          ignored files to prevent warnings about undocumented symbols.
     47    headers            -- A list of paths to headers to be scanned. Required if source_dirs
     48                          is not specified.
    4649    namespace          -- The library namespace.
    4750    decorator          -- If a decorator is used to unhide certain symbols in header
    … …  
    8891        self.module_name = ''
    8992        self.source_dirs = []
     93        self.headers = []
    9094        self.ignored_files = []
    9195        self.namespace = ''
    … …  
    113117            setattr(self, key, value)
    114118
    115         def raise_error_if_not_specified(key):
    116             if not getattr(self, key):
    117                 raise Exception('%s not specified.' % key)
    118 
    119         raise_error_if_not_specified('output_dir')
    120         raise_error_if_not_specified('source_dirs')
    121         raise_error_if_not_specified('module_name')
     119        if not getattr(self, 'output_dir'):
     120            raise Exception('output_dir not specified.')
     121        if not getattr(self, 'module_name'):
     122            raise Exception('module_name not specified.')
     123        if not getattr(self, 'source_dirs') and not getattr(self, 'headers'):
     124            raise Exception('Neither source_dirs nor headers specified.' % key)
    122125
    123126        # Make all paths absolute in case we were passed relative paths, since
    … …  
    125128        self.output_dir = os.path.abspath(self.output_dir)
    126129        self.source_dirs = [os.path.abspath(x) for x in self.source_dirs]
     130        self.headers = [os.path.abspath(x) for x in self.headers]
    127131        if self.library_path:
    128132            self.library_path = os.path.abspath(self.library_path)
    … …  
    275279                '--rebuild-types']
    276280
    277         # Each source directory should be have its own "--source-dir=" prefix.
    278         args.extend(['--source-dir=%s' % path for path in self.source_dirs])
     281        if not self.headers:
     282            # Each source directory should be have its own "--source-dir=" prefix.
     283            args.extend(['--source-dir=%s' % path for path in self.source_dirs])
    279284
    280285        if self.decorator:
    … …  
    285290            args.append('--output-dir=%s' % self.output_dir)
    286291
    287         # gtkdoc-scan wants the basenames of ignored headers, so strip the
    288         # dirname. Different from "--source-dir", the headers should be
    289         # specified as one long string.
    290         ignored_files_basenames = self._ignored_files_basenames()
    291         if ignored_files_basenames:
    292             args.append('--ignore-headers=%s' % ignored_files_basenames)
     292        # We only need to pass the list of ignored files if the we are not using an explicit list of headers.
     293        if not self.headers:
     294            # gtkdoc-scan wants the basenames of ignored headers, so strip the
     295            # dirname. Different from "--source-dir", the headers should be
     296            # specified as one long string.
     297            ignored_files_basenames = self._ignored_files_basenames()
     298            if ignored_files_basenames:
     299                args.append('--ignore-headers=%s' % ignored_files_basenames)
     300
     301        if self.headers:
     302            args.extend(self.headers)
    293303
    294304        self._run_command(args)
Note: See TracChangeset for help on using the changeset viewer.