Changeset 165114 in webkit


Ignore:
Timestamp:
Mar 5, 2014 10:37:59 AM (10 years ago)
Author:
Martin Robinson
Message:

[GTK][CMake] Generate documentation for the DOM bindings
​https://bugs.webkit.org/show_bug.cgi?id=126211

Reviewed by Carlos Garcia Campos.

Source/WebCore:

  • PlatformGTK.cmake: Add some files to the GObjectDOMBindings build, so that the

doc generation succeeds. Have the GObjectDOMBindings_INSTALLED_HEADERS variable contain
all installed headers and use another variable for GIR generation. Create the configuration
file for the gtkdoc generation.

Source/WebKit:

  • PlatformGTK.cmake: The list of headers for GIR generation has a better name

now.

Source/WebKit2:

  • PlatformGTK.cmake: The list of headers for GIR generation has a better name now.

Tools:

  • gtk/GNUmakefile.am: No longer generation sections and SGML files in the makefile.
  • gtk/generate-gtkdoc: Call the code from webkitdom.py to generate sections and SGML files.
  • gtk/generate-webkitdom-doc-files: Removed.
  • gtk/webkitdom.py: Moved WebKit GObject DOM bindings doc generation code here, so

that it can be called by generate-gtkdoc.

Location:
trunk
Files:
1 deleted
10 edited

Legend:

Unmodified
Added
Removed

  • trunk/Source/WebCore/ChangeLog

    r165113 r165114  
     12014-03-03  Martin Robinson  <mrobinson@igalia.com>
     2
     3        [GTK][CMake] Generate documentation for the DOM bindings
     4        https://bugs.webkit.org/show_bug.cgi?id=126211
     5
     6        Reviewed by Carlos Garcia Campos.
     7
     8        * PlatformGTK.cmake: Add some files to the GObjectDOMBindings build, so that the
     9        doc generation succeeds. Have the GObjectDOMBindings_INSTALLED_HEADERS variable contain
     10        all installed headers and use another variable for GIR generation. Create the configuration
     11        file for the gtkdoc generation.
     12
    1132014-03-05  Zalan Bujtas  <zalan@apple.com>
    214

  • trunk/Source/WebCore/PlatformGTK.cmake

    r165060 r165114  
    482482        bindings/gobject/GObjectEventListener.cpp
    483483        bindings/gobject/WebKitDOMCustom.cpp
     484        bindings/gobject/WebKitDOMDeprecated.cpp
    484485        bindings/gobject/WebKitDOMEventTarget.cpp
    485486        bindings/gobject/WebKitDOMHTMLPrivate.cpp
    … …  
    667668         ${DERIVED_SOURCES_GOBJECT_DOM_BINDINGS_DIR}/webkitdom.h
    668669         ${WEBCORE_DIR}/bindings/gobject/WebKitDOMCustom.h
     670         ${WEBCORE_DIR}/bindings/gobject/WebKitDOMDeprecated.h
     671         ${WEBCORE_DIR}/bindings/gobject/WebKitDOMEventTarget.h
     672         ${WEBCORE_DIR}/bindings/gobject/WebKitDOMObject.h
    669673    )
    670674    file(GLOB GObjectDOMBindingsSymbolsFiles
    … …  
    678682        list(APPEND GObjectDOMBindingsSymbolsFiles ${DERIVED_SOURCES_GOBJECT_DOM_BINDINGS_DIR}/WebKitDOM${classname}.symbols)
    679683    endforeach ()
    680 
    681     # Propagate this variable to the parent scope, so that it can be used in other parts of the build.
    682     set(GObjectDOMBindings_INSTALLED_HEADERS ${GObjectDOMBindings_INSTALLED_HEADERS} PARENT_SCOPE)
    683684
    684685    set(GOBJECT_DOM_BINDINGS_FEATURES_DEFINES "LANGUAGE_GOBJECT=1 ${FEATURE_DEFINES_WITH_SPACE_SEPARATOR}")
    … …  
    727728    )
    728729
     730    file(WRITE ${CMAKE_BINARY_DIR}/gtkdoc-webkitdom.cfg
     731        "[webkitdomgtk]\n"
     732        "pkgconfig_file=${WebKit2_PKGCONFIG_FILE}\n"
     733        "namespace=webkit_dom\n"
     734        "cflags=-I${CMAKE_SOURCE_DIR}/Source\n"
     735        "       -I${WEBCORE_DIR}/bindings\n"
     736        "       -I${WEBCORE_DIR}/bindings/gobject\n"
     737        "       -I${DERIVED_SOURCES_GOBJECT_DOM_BINDINGS_DIR}\n"
     738        "doc_dir=${DERIVED_SOURCES_GOBJECT_DOM_BINDINGS_DIR}/docs\n"
     739        "source_dirs=${DERIVED_SOURCES_GOBJECT_DOM_BINDINGS_DIR}\n"
     740        "            ${WEBCORE_DIR}/bindings/gobject\n"
     741        "headers=${GObjectDOMBindings_INSTALLED_HEADERS}\n"
     742    )
     743
    729744    install(FILES ${GObjectDOMBindings_INSTALLED_HEADERS}
    730                   bindings/gobject/WebKitDOMEventTarget.h
    731                   bindings/gobject/WebKitDOMDeprecated.h
    732                   bindings/gobject/WebKitDOMObject.h
    733745            DESTINATION "${WEBKITGTK_HEADER_INSTALL_DIR}/webkitdom"
    734746    )
    735 endif ()
    736 
     747
     748    # Some installed headers are not on the list of headers used for gir generation.
     749    set(GObjectDOMBindings_GIR_HEADERS ${GObjectDOMBindings_INSTALLED_HEADERS})
     750    list(REMOVE_ITEM GObjectDOMBindings_GIR_HEADERS
     751         bindings/gobject/WebKitDOMEventTarget.h
     752         bindings/gobject/WebKitDOMDeprecated.h
     753         bindings/gobject/WebKitDOMObject.h)
     754
     755    # Propagate this variable to the parent scope, so that it can be used in other parts of the build.
     756    set(GObjectDOMBindings_GIR_HEADERS ${GObjectDOMBindings_GIR_HEADERS} PARENT_SCOPE)
     757
     758endif ()
     759

  • trunk/Source/WebKit/ChangeLog

    r165027 r165114  
     12014-03-03  Martin Robinson  <mrobinson@igalia.com>
     2
     3        [GTK][CMake] Generate documentation for the DOM bindings
     4        https://bugs.webkit.org/show_bug.cgi?id=126211
     5
     6        Reviewed by Carlos Garcia Campos.
     7
     8        * PlatformGTK.cmake: The list of headers for GIR generation has a better name
     9        now.
     10
    1112014-03-03  Commit Queue  <commit-queue@webkit.org>
    212

  • trunk/Source/WebKit/PlatformGTK.cmake

    r164632 r165114  
    201201        -I${DERIVED_SOURCES_WEBKITGTK_DIR}
    202202        -I${WEBCORE_DIR}/platform/gtk
    203         ${GObjectDOMBindings_INSTALLED_HEADERS}
     203        ${GObjectDOMBindings_GIR_HEADERS}
    204204        ${WebKitGTK_INSTALLED_HEADERS}
    205205        ${WEBKIT_DIR}/gtk/webkit/*.cpp

  • trunk/Source/WebKit2/ChangeLog

    r165096 r165114  
     12014-03-03  Martin Robinson  <mrobinson@igalia.com>
     2
     3        [GTK][CMake] Generate documentation for the DOM bindings
     4        https://bugs.webkit.org/show_bug.cgi?id=126211
     5
     6        Reviewed by Carlos Garcia Campos.
     7
     8        * PlatformGTK.cmake: The list of headers for GIR generation has a better name now.
     9
    1102014-03-04  Benjamin Poulain  <bpoulain@apple.com>
    211

  • trunk/Source/WebKit2/PlatformGTK.cmake

    r164973 r165114  
    757757        -I${FORWARDING_HEADERS_WEBKIT2GTK_EXTENSION_DIR}
    758758        -I${WEBKIT2_DIR}/WebProcess/InjectedBundle/API/gtk
    759         ${GObjectDOMBindings_INSTALLED_HEADERS}
     759        ${GObjectDOMBindings_GIR_HEADERS}
    760760        ${WebKit2WebExtension_INSTALLED_HEADERS}
    761761        ${WEBKIT2_DIR}/WebProcess/InjectedBundle/API/gtk/*.cpp

  • trunk/Tools/ChangeLog

    r165111 r165114  
     12014-03-03  Martin Robinson  <mrobinson@igalia.com>
     2
     3        [GTK][CMake] Generate documentation for the DOM bindings
     4        https://bugs.webkit.org/show_bug.cgi?id=126211
     5
     6        Reviewed by Carlos Garcia Campos.
     7
     8        * gtk/GNUmakefile.am: No longer generation sections and SGML files in the makefile.
     9        * gtk/generate-gtkdoc: Call the code from webkitdom.py to generate sections and SGML files.
     10        * gtk/generate-webkitdom-doc-files: Removed.
     11        * gtk/webkitdom.py: Moved WebKit GObject DOM bindings doc generation code here, so
     12        that it can be called by generate-gtkdoc.
     13
    1142014-03-05  Martin Robinson  <mrobinson@igalia.com>
    215

  • trunk/Tools/gtk/GNUmakefile.am

    r165060 r165114  
    3131endif
    3232
    33 $(top_builddir)/DerivedSources/webkitdom/docs/webkitdomgtk-docs.sgml: $(gdom_symbol_files) $(srcdir)/Tools/gtk/generate-webkitdom-doc-files
    34         $(AM_V_GEN)mkdir -p $(top_builddir)/DerivedSources/webkitdom/docs \
    35         && echo $(gdom_symbol_files) | $(PYTHON) $(srcdir)/Tools/gtk/generate-webkitdom-doc-files docs > $@
    36 
    37 $(top_builddir)/DerivedSources/webkitdom/docs/webkitdomgtk-sections.txt: $(gdom_symbol_files) $(srcdir)/Tools/gtk/generate-webkitdom-doc-files
    38         $(AM_V_GEN)mkdir -p $(top_builddir)/DerivedSources/webkitdom/docs \
    39         && echo $(gdom_symbol_files) | $(PYTHON) $(srcdir)/Tools/gtk/generate-webkitdom-doc-files sections > $@
    40 
    41 BUILT_SOURCES += \
    42         $(top_builddir)/DerivedSources/webkitdom/docs/webkitdomgtk-docs.sgml \
    43         $(top_builddir)/DerivedSources/webkitdom/docs/webkitdomgtk-sections.txt
    44 
    4533docs_build_dependencies += \
    4634        libGObjectDOMBindings.la \
    47         $(top_builddir)/DerivedSources/webkitdom/docs/webkitdomgtk-docs.sgml \
    48         $(top_builddir)/DerivedSources/webkitdom/docs/webkitdomgtk-sections.txt \
    4935        gtkdoc-webkitdom.cfg
    5036

  • trunk/Tools/gtk/generate-gtkdoc

    r164704 r165114  
    2626import os.path
    2727import sys
     28import webkitdom
    2829
    2930def configure_logging(verbose):
    … …  
    195196    prepare_environment_for_gtkdoc_generation()
    196197
     198    webkitdom.write_doc_files()
     199    generate_documentation_for_config(common.build_path('gtkdoc-webkitdom.cfg'))
     200
    197201    saw_webkit1_warnings = generate_documentation_for_config(common.build_path('gtkdoc-webkitgtk.cfg'))
    198202    saw_webkit2_warnings = generate_documentation_for_config(common.build_path('gtkdoc-webkit2gtk.cfg'))
    199     if not common.is_cmake_build():
    200         generate_documentation_for_config(common.build_path('gtkdoc-webkitdom.cfg'))
    201203
    202204    sys.exit(saw_webkit1_warnings or saw_webkit2_warnings)

  • trunk/Tools/gtk/webkitdom.py

    r165060 r165114  
    1919import common
    2020import os
     21import re
    2122import sys
    2223
    2324from ConfigParser import SafeConfigParser
     25
     26
     27class WebKitDOMDocGenerator(object):
     28
     29    DELETED_CLASSES = [
     30        "WebKitDOMBarInfo",
     31        "WebKitDOMHTMLPropertiesCollection",
     32        "WebKitDOMMemoryInfo",
     33        "WebKitDOMMicroDataItemValue",
     34        "WebKitDOMPropertyNodeList"]
     35
     36    def __init__(self, symbol_files, file_handle):
     37        self._symbol_files = symbol_files
     38        self._file_handle = file_handle
     39
     40    def write_header(self):
     41        pass
     42
     43    def write_section(self, symbol_file):
     44        raise NotImplementedError
     45
     46    def write_deleted_classes(self):
     47        raise NotImplementedError
     48
     49    def write_footer(self):
     50        pass
     51
     52    def write(self, string):
     53        self._file_handle.write(string)
     54
     55    @staticmethod
     56    def is_deprecated_symbol_file(file_path):
     57        return 'WebKitDOMDeprecated' in file_path
     58
     59    def generate(self):
     60        self.write_header()
     61        for symbol_file in self._symbol_files:
     62            if WebKitDOMDocGenerator.is_deprecated_symbol_file(symbol_file):
     63                continue
     64            self.write_section(symbol_file)
     65        self.write_deleted_classes()
     66        self.write_footer()
     67
     68
     69class WebKitDOMDocGeneratorSGML(WebKitDOMDocGenerator):
     70    def write_header(self):
     71        self.write('''<?xml version="1.0"?>
     72<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
     73               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
     74<!ENTITY version SYSTEM "version.xml">
     75]>
     76<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
     77  <bookinfo>
     78    <title>WebKitDOMGTK+ Reference Manual</title>
     79    <releaseinfo>for WebKitDOMGTK+ &version;</releaseinfo>
     80  </bookinfo>
     81
     82  <chapter>
     83    <title>Class Overview</title>
     84''')
     85
     86    def write_section(self, symbol_file):
     87        basename = os.path.basename(symbol_file)
     88        self.write('    <xi:include href="xml/%s"/>\n' % basename.replace(".symbols", ".xml"))
     89
     90    def write_deleted_classes(self):
     91        for class_name in self.DELETED_CLASSES:
     92            self.write('    <xi:include href="xml/%s.xml"/>\n' % class_name)
     93
     94    def write_footer(self):
     95        self.write('''  </chapter>
     96
     97  <index id="index-all">
     98    <title>Index</title>
     99    <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
     100  </index>
     101  <index id="api-index-deprecated" role="deprecated">
     102    <title>Index of deprecated symbols</title>
     103    <xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>
     104  </index>
     105
     106  <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
     107</book>
     108''')
     109
     110
     111class WebKitDOMDocGeneratorSections(WebKitDOMDocGenerator):
     112    def __init__(self, symbol_files, file_handle):
     113        super(WebKitDOMDocGeneratorSections, self).__init__(symbol_files, file_handle)
     114
     115        self._first_decamelize_re = re.compile('(.)([A-Z][a-z]+)')
     116        self._second_decamelize_re = re.compile('([a-z0-9])([A-Z])')
     117        self._dom_class_re = re.compile('(^WebKitDOM)(.+)$')
     118        self._function_re = re.compile('^.+ (.+)\((.+)\)$')
     119
     120        self.deprecated_symbosl = {}
     121        for symbol_file in symbol_files:
     122            if WebKitDOMDocGenerator.is_deprecated_symbol_file(symbol_file):
     123                self._deprecated_symbols = self._find_deprecated_symbols(symbol_file)
     124                break
     125
     126    def _dom_class(self, class_name):
     127        return self._dom_class_re.sub(r'\2', class_name)
     128
     129    def _dom_class_decamelize(self, class_name):
     130        s1 = self._first_decamelize_re.sub(r'\1_\2', self._dom_class(class_name))
     131        retval = self._second_decamelize_re.sub(r'\1_\2', s1)
     132
     133        # Fix some exceptions.
     134        retval = retval.replace('Web_Kit', 'WebKit')
     135        retval = retval.replace('X_Path', 'XPath')
     136        retval = retval.replace('HTMLI_Frame', 'HTML_IFrame')
     137
     138        return retval
     139
     140    def _deleted_class(self, function):
     141        for deleted_class in self.DELETED_CLASSES:
     142            decamelized = 'webkit_dom_%s' % self._dom_class_decamelize(deleted_class).lower()
     143            if function.startswith(decamelized):
     144                return deleted_class
     145        return None
     146
     147    def _find_deprecated_symbols(self, symbol_file):
     148        retval = {}
     149        f = open(symbol_file, 'r')
     150        for line in f.readlines():
     151            match = self._function_re.match(line)
     152            if not match:
     153                continue
     154
     155            function = match.group(1)
     156            args = match.group(2).split(', ')
     157            class_name = args[0].strip('*')
     158            if class_name == 'void':
     159                class_name = self._deleted_class(function)
     160
     161            retval.setdefault(class_name, []).append(function)
     162
     163        return retval
     164
     165    def _symbol_list(self, symbol_file):
     166        retval = []
     167        f = open(symbol_file, 'r')
     168        for line in f.readlines():
     169            match = self._function_re.match(line)
     170            if not match or match.group(1).endswith('get_type'):
     171                continue
     172            retval.append(match.group(1))
     173
     174        return retval
     175
     176    def write_section(self, symbol_file):
     177        class_name = os.path.basename(symbol_file).replace(".symbols", "")
     178        is_custom = class_name == 'WebKitDOMCustom'
     179        is_interface = class_name == 'WebKitDOMEventTarget'
     180        is_object = class_name == 'WebKitDOMObject'
     181        self.write('<SECTION>\n')
     182        self.write('<FILE>%s</FILE>\n<TITLE>%s</TITLE>\n' % (class_name, class_name))
     183        if not is_custom:
     184            self.write('%s\n' % class_name)
     185        self.write('\n')
     186        self.write('\n'.join(self._symbol_list(symbol_file)) + '\n')
     187        try:
     188            deprecated_functions = self._deprecated_symbols[class_name]
     189            self.write('\n'.join(deprecated_functions) + '\n')
     190        except KeyError:
     191            pass
     192        if not is_custom:
     193            self.write('\n<SUBSECTION Standard>\n')
     194            self.write('%sClass\n' % class_name)
     195            dom_class = self._dom_class_decamelize(class_name).upper()
     196            self.write('WEBKIT_TYPE_DOM_%s\n' % dom_class)
     197            self.write('WEBKIT_DOM_%s\n' % dom_class)
     198            if is_object:
     199                self.write('WEBKIT_IS_DOM_%s\n' % dom_class)
     200            else:
     201                self.write('WEBKIT_DOM_IS_%s\n' % dom_class)
     202            self.write('WEBKIT_DOM_%s_CLASS\n' % dom_class)
     203            if is_interface:
     204                self.write('WEBKIT_DOM_%s_GET_IFACE\n' % dom_class)
     205            else:
     206                if is_object:
     207                    self.write('WEBKIT_IS_DOM_%s_CLASS\n' % dom_class)
     208                else:
     209                    self.write('WEBKIT_DOM_IS_%s_CLASS\n' % dom_class)
     210                self.write('WEBKIT_DOM_%s_GET_CLASS\n' % dom_class)
     211            self.write('\n<SUBSECTION Private>\n')
     212            if is_object:
     213                self.write('%sPrivate\n' % class_name)
     214            self.write('webkit_dom_%s_get_type\n' % dom_class.lower())
     215        self.write('</SECTION>\n\n')
     216
     217    def write_deleted_classes(self):
     218        for class_name in self.DELETED_CLASSES:
     219            self.write('<SECTION>\n')
     220            self.write('<FILE>%s</FILE>\n<TITLE>%s</TITLE>\n' % (class_name, class_name))
     221            self.write('\n'.join([name for name in self._deprecated_symbols[class_name] if not name.endswith('get_type')]) + '\n')
     222            self.write('\n<SUBSECTION Private>\n')
     223            self.write('webkit_dom_%s_get_type\n' % self._dom_class_decamelize(class_name).lower())
     224            self.write('</SECTION>\n\n')
     225
     226    def write_footer(self):
     227        self.write('<SECTION>\n')
     228        self.write('<FILE>webkitdomdefines</FILE>\n<TITLE>WebKitDOMDefines</TITLE>\n')
     229        self.write('<SUBSECTION Private>\n')
     230        self.write('WEBKIT_API\nWEBKIT_DEPRECATED\nWEBKIT_DEPRECATED_FOR\n')
     231        self.write('</SECTION>\n\n')
     232
     233
     234def write_doc_files():
     235    doc_dir = common.build_path('DerivedSources', 'webkitdom', 'docs')
     236
     237    try:
     238        os.mkdir(doc_dir)
     239    except:
     240        pass  # Commonly happens if the directory already exists.
     241
     242    with open(os.path.join(doc_dir, 'webkitdomgtk-sections.txt'), 'w') as sections_file:
     243        generator = WebKitDOMDocGeneratorSections(get_all_webkitdom_symbol_files(), sections_file)
     244        generator.generate()
     245    with open(os.path.join(doc_dir, 'webkitdomgtk-docs.sgml'), 'w') as sgml_file:
     246        generator = WebKitDOMDocGeneratorSGML(get_all_webkitdom_symbol_files(), sgml_file)
     247        generator.generate()
    24248
    25249
Note: See TracChangeset for help on using the changeset viewer.