[GTK] Generate API documentation for GObject DOM bindings
[WebKit-https.git] / Tools / gtk / generate-gtkdoc
1 #!/usr/bin/env python
2 # Copyright (C) 2011 Igalia S.L.
3 #
4 # This library is free software; you can redistribute it and/or
5 # modify it under the terms of the GNU Lesser General Public
6 # License as published by the Free Software Foundation; either
7 # version 2 of the License, or (at your option) any later version.
8 #
9 # This library is distributed in the hope that it will be useful,
10 # but WITHOUT ANY WARRANTY; without even the implied warranty of
11 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
12 # Lesser General Public License for more details.
13 #
14 # You should have received a copy of the GNU Lesser General Public
15 # License along with this library; if not, write to the Free Software
16 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
17
18 import common
19 import glob
20 import gtkdoc
21 import logging
22 import os.path
23 import sys
24
25 def configure_logging():
26     level = logging.DEBUG if '-v' in sys.argv else logging.INFO
27     logger = logging.getLogger('gtkdoc')
28     logger.setLevel(level)
29     handler = logging.StreamHandler()
30     handler.setLevel(level)
31     logger.addHandler(handler)
32     if level == logging.DEBUG:
33         handler.setFormatter(logging.Formatter('[%(asctime)s]  %(message)s'))
34     else:
35         handler.setFormatter(logging.Formatter('%(message)s'))
36
37
38 def get_gtkdoc_module_paths(xref_dep_packages):
39     deps = []
40     html_dir = os.path.join('share', 'gtk-doc', 'html')
41
42     for package in xref_dep_packages:
43         prefix = common.prefix_of_pkg_config_file(package)
44         if prefix is None:
45             continue
46         for module in xref_dep_packages[package]:
47             deps.append(os.path.join(prefix, html_dir, module))
48
49     return deps
50
51
52 def get_common_options():
53     # TODO: We should consider using an arguments parsing library if
54     # we need more of these complex ones.
55     virtual_root = ''
56     for argument in sys.argv:
57         if argument.startswith('--virtual-root='):
58             virtual_root = argument.split('=')[1]
59             break
60
61     return {
62         'decorator': 'WEBKIT_API',
63         'deprecation_guard': 'WEBKIT_DISABLE_DEPRECATED',
64         'library_path' : common.build_path('.libs'),
65         'virtual_root' : virtual_root,
66     }
67
68 def get_common_xref_deps():
69     return {
70         'glib-2.0' : ['glib', 'gobject', 'gio'],
71         'libsoup-2.4' : ['libsoup-2.4'],
72         'gdk-pixbuf-2.0': ['gdk-pixbuf']
73     }
74
75 def webkitdom_docs_html_path():
76     return common.build_path('Documentation', 'webkitdomgtk', 'html')
77
78 def get_webkit2_options():
79     def derived_sources_path(*args):
80         return common.build_path(*(('DerivedSources', 'WebKit2') + args))
81     def src_path(*args):
82         return common.top_level_path(*(('Source', 'WebKit2', 'UIProcess', 'API', 'gtk') + args))
83     def injected_bundle_src_path(*args):
84         return common.top_level_path(*(('Source', 'WebKit2', 'WebProcess', 'InjectedBundle', 'API', 'gtk') + args))
85
86     xref_deps = get_common_xref_deps().copy()
87     xref_deps.update({
88         'gtk+-3.0' : ['gtk3', 'gdk3']
89     })
90
91     options = get_common_options().copy()
92     options.update({
93         'module_name' : 'webkit2gtk',
94         'doc_dir' : src_path('docs'),
95         'output_dir' : common.build_path('Documentation', 'webkit2gtk'),
96         'source_dirs' : [src_path(), derived_sources_path('webkit2gtk', 'webkit2'), injected_bundle_src_path()],
97         'cflags' : ' -I' + derived_sources_path('webkit2gtk', 'include') + \
98                    ' -I' + derived_sources_path('webkit2gtk') + \
99                    ' -I' + derived_sources_path('include') + \
100                    ' -I' + common.top_level_path('Source') + \
101                    ' -I' + src_path(),
102         'cross_reference_deps' : get_gtkdoc_module_paths(xref_deps) + [webkitdom_docs_html_path()],
103         'ignored_files': glob.glob(src_path('*Private.h')) + \
104                          glob.glob(injected_bundle_src_path('*Private.h')) + \
105                          glob.glob(src_path('*Client*')) + \
106                          glob.glob(src_path('WebKitGeolocationProvider.*')) + \
107                          glob.glob(src_path('WebKitTextChecker.*')) + \
108                          glob.glob(src_path('WebKitAuthenticationDialog.*')) + \
109                          glob.glob(src_path('WebKitWebViewBaseAccessible.*')) + \
110                          glob.glob(src_path('WebViewBaseInputMethodFilter.*')) + \
111                          glob.glob(derived_sources_path('webkit2gtk', 'webkit2', 'WebKitMarshal.*')) + \
112                          glob.glob(derived_sources_path('webkit2gtk', 'webkit2', 'WebKitEnumTypes.*')) + \
113                          glob.glob(src_path('tests/*.h'))
114     })
115     return options
116
117 def get_webkit1_options(gtk_version):
118     def src_path(*args):
119         return common.top_level_path(*(('Source', 'WebKit', 'gtk') + args))
120
121     xref_deps = get_common_xref_deps().copy()
122     if gtk_version == 3:
123         xref_deps.update({
124                 'gtk+-3.0' : ['gtk3', 'gdk3']
125         })
126     else:
127         xref_deps.update({
128                 'gtk+-2.0' : ['gtk', 'gdk']
129         })
130
131     options = get_common_options().copy()
132     options.update({
133         'module_name' : 'webkitgtk',
134         'doc_dir' : src_path('docs'),
135         'output_dir' : common.build_path('Documentation', 'webkitgtk'),
136         'source_dirs' : [src_path('webkit'), common.build_path('Source', 'WebKit', 'gtk', 'webkit')],
137         'cflags' : ' -I' + common.build_path('WebKit', 'gtk') + \
138                    ' -I' + common.build_path('DerivedSources') + \
139                    ' -I' + src_path() + \
140                    ' -I' + common.top_level_path('Source') + \
141                    ' -I' + common.top_level_path('Source', 'JavaScriptCore', 'ForwardingHeaders'),
142         'cross_reference_deps' : get_gtkdoc_module_paths(xref_deps) + [webkitdom_docs_html_path()],
143         'ignored_files': glob.glob(src_path('webkit', '*private.*')) + \
144                          glob.glob(src_path('webkit', 'webkitauthenticationdialog.*')) + \
145                          glob.glob(src_path('webkit', 'webkitspellcheckerenchant.*'))
146     })
147     return options
148
149 def get_webkitdom_options():
150     def derived_sources_path(*args):
151         return common.build_path(*(('DerivedSources', 'webkitdom') + args))
152     def src_path(*args):
153         return common.top_level_path(*(('Source', 'WebCore', 'bindings', 'gobject') + args))
154
155     xref_deps = { 'glib-2.0' : ['glib', 'gobject', 'gio'] }
156
157     options = get_common_options().copy()
158     options.update({
159         'module_name' : 'webkitdomgtk',
160         'doc_dir' : derived_sources_path('docs'),
161         'output_dir' : common.build_path('Documentation', 'webkitdomgtk'),
162         'source_dirs' : [derived_sources_path()],
163         'cflags' : ' -I' + derived_sources_path() + \
164                    ' -I' + src_path() + \
165                    ' -I' + common.top_level_path('Source'),
166         'cross_reference_deps' : get_gtkdoc_module_paths(xref_deps),
167         'ignored_files': glob.glob(derived_sources_path('*Private.h'))
168     })
169     return options
170
171 def print_missing_api(generator):
172     missing_api = generator.api_missing_documentation()
173     if not missing_api:
174         return
175     print("\nThe following API are missing documentation:")
176     for api in missing_api:
177         print("\t%s" % api)
178
179 def generate_doc(generator):
180     generator.generate(html='--skip-html' not in sys.argv)
181     if generator.saw_warnings:
182         print_missing_api(generator)
183     return generator.saw_warnings
184
185 configure_logging()
186
187 # We need to add the JavaScriptCore build directory to the PKG_CONFIG_PATH
188 # so that pkgconfig can properly resolve the libjavascriptcore dependency.
189 pkg_config_path = os.environ.get("PKG_CONFIG_PATH")
190 os.environ['PKG_CONFIG_PATH'] = common.build_path('Source', 'JavaScriptCore')
191 if pkg_config_path:
192     os.environ['PKG_CONFIG_PATH'] += ':' + pkg_config_path
193
194 # Newer versions of glib have deprecated g_type_init, so we need to disable
195 # that warning when running gtkdoc-scanobj by overriding the CFLAGS we use
196 # to compile it.
197 cflags = os.environ.get('CFLAGS', '')
198 cflags += ' -DGLIB_VERSION_MIN_REQUIRED=GLIB_VERSION_2_32'
199 os.environ['CFLAGS'] = cflags
200
201 # Clang can be noisy, throwing unnecessary warnings for unused arguments.
202 if os.environ.get('CC') == "clang":
203     os.environ['CFLAGS'] += ' -Qunused-arguments'
204
205 saw_webkit1_warnings = saw_webkit2_warnings = False
206 wk2_pkg_config_path = common.build_path('Source', 'WebKit2', 'webkit2gtk-3.0.pc')
207 wk1_pkg_config_path = common.build_path('Source', 'WebKit', 'gtk', 'webkitgtk-3.0.pc')
208 if not os.path.exists(wk1_pkg_config_path):
209     wk1_pkg_config_path = common.build_path('Source', 'WebKit', 'gtk', 'webkit-1.0.pc')
210
211 if os.path.exists(wk2_pkg_config_path):
212     pkg_config_path = wk2_pkg_config_path
213 elif os.path.exists(wk1_pkg_config_path):
214     pkg_config_path = wk1_pkg_config_path
215 generator = gtkdoc.PkgConfigGTKDoc(pkg_config_path, get_webkitdom_options())
216 if '--rebase' not in sys.argv:
217     print("\nGenerating WebKitDOM documentation...")
218     saw_webkitdom_warnings = generate_doc(generator)
219 else:
220     print("\nRebasing WebKitDOM documentation...")
221     try:
222         generator.rebase_installed_docs()
223     except Exception:
224         print("Rebase did not happen, likely no documentation is present.")
225
226 pkg_config_path = wk1_pkg_config_path
227 if os.path.exists(pkg_config_path):
228     options = get_webkit1_options(common.gtk_version_of_pkg_config_file(pkg_config_path))
229     generator = gtkdoc.PkgConfigGTKDoc(pkg_config_path, options)
230     if '--rebase' not in sys.argv:
231         print("Generating WebKit1 documentation...")
232         saw_webkit1_warnings = generate_doc(generator)
233     else:
234         print("Rebasing WebKit1 documentation...")
235         try:
236             generator.rebase_installed_docs()
237         except Exception:
238             print("Rebase did not happen, likely no documentation is present.")
239
240 # WebKit2 might not be enabled, so check for the pkg-config file before building documentation.
241 pkg_config_path = wk2_pkg_config_path
242 if os.path.exists(pkg_config_path):
243     generator = gtkdoc.PkgConfigGTKDoc(pkg_config_path, get_webkit2_options())
244     if '--rebase' not in sys.argv:
245         print("\nGenerating WebKit2 documentation...")
246         saw_webkit2_warnings = generate_doc(generator)
247     else:
248         print("\nRebasing WebKit2 documentation...")
249         try:
250             generator.rebase_installed_docs()
251         except Exception:
252             print("Rebase did not happen, likely no documentation is present.")
253
254 sys.exit(saw_webkit1_warnings or saw_webkit2_warnings)