36fac4dd7ea74abbecf7e8bdedf972e110a4f2fa
[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|WEBKIT_DEPRECATED|WEBKIT_DEPRECATED_FOR\(.+\)',
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         'namespace' : 'webkit',
95         'doc_dir' : src_path('docs'),
96         'output_dir' : common.build_path('Documentation', 'webkit2gtk'),
97         'source_dirs' : [src_path(), derived_sources_path('webkit2gtk', 'webkit2'), injected_bundle_src_path()],
98         'cflags' : ' -I' + derived_sources_path('webkit2gtk', 'include') + \
99                    ' -I' + derived_sources_path('webkit2gtk') + \
100                    ' -I' + derived_sources_path('include') + \
101                    ' -I' + common.top_level_path('Source') + \
102                    ' -I' + src_path(),
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(injected_bundle_src_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(derived_sources_path('webkit2gtk', 'webkit2', 'WebKitMarshal.*')) + \
114                          glob.glob(derived_sources_path('webkit2gtk', 'webkit2', 'WebKitEnumTypes.*')) + \
115                          glob.glob(src_path('tests/*.h'))
116     })
117     return options
118
119 def get_webkit1_options(gtk_version):
120     def src_path(*args):
121         return common.top_level_path(*(('Source', 'WebKit', 'gtk') + args))
122
123     xref_deps = get_common_xref_deps().copy()
124     if gtk_version == 3:
125         xref_deps.update({
126                 'gtk+-3.0' : ['gtk3', 'gdk3']
127         })
128     else:
129         xref_deps.update({
130                 'gtk+-2.0' : ['gtk', 'gdk']
131         })
132
133     options = get_common_options().copy()
134     options.update({
135         'module_name' : 'webkitgtk',
136         'namespace' : 'webkit',
137         'doc_dir' : src_path('docs'),
138         'output_dir' : common.build_path('Documentation', 'webkitgtk'),
139         'source_dirs' : [src_path('webkit'), common.build_path('Source', 'WebKit', 'gtk', 'webkit')],
140         'cflags' : ' -I' + common.build_path('WebKit', 'gtk') + \
141                    ' -I' + common.build_path('DerivedSources') + \
142                    ' -I' + src_path() + \
143                    ' -I' + common.top_level_path('Source') + \
144                    ' -I' + common.top_level_path('Source', 'JavaScriptCore', 'ForwardingHeaders'),
145         'cross_reference_deps' : get_gtkdoc_module_paths(xref_deps) + [webkitdom_docs_html_path()],
146         'ignored_files': glob.glob(src_path('webkit', '*private.*')) + \
147                          glob.glob(src_path('webkit', 'webkitauthenticationdialog.*')) + \
148                          glob.glob(src_path('webkit', 'webkitspellcheckerenchant.*'))
149     })
150     return options
151
152 def get_webkitdom_options():
153     def derived_sources_path(*args):
154         return common.build_path(*(('DerivedSources', 'webkitdom') + args))
155     def src_path(*args):
156         return common.top_level_path(*(('Source', 'WebCore', 'bindings', 'gobject') + args))
157
158     xref_deps = { 'glib-2.0' : ['glib', 'gobject', 'gio'] }
159
160     options = get_common_options().copy()
161     options.update({
162         'module_name' : 'webkitdomgtk',
163         'namespace' : 'webkit_dom',
164         'doc_dir' : derived_sources_path('docs'),
165         'output_dir' : common.build_path('Documentation', 'webkitdomgtk'),
166         'source_dirs' : [derived_sources_path()],
167         'cflags' : ' -I' + derived_sources_path() + \
168                    ' -I' + src_path() + \
169                    ' -I' + common.top_level_path('Source'),
170         'cross_reference_deps' : get_gtkdoc_module_paths(xref_deps),
171         'ignored_files': glob.glob(derived_sources_path('*Private.h'))
172     })
173     return options
174
175 def print_missing_api(generator):
176     missing_api = generator.api_missing_documentation()
177     if not missing_api:
178         return
179     print("\nThe following API are missing documentation:")
180     for api in missing_api:
181         print("\t%s" % api)
182
183 def generate_doc(generator):
184     generator.generate(html='--skip-html' not in sys.argv)
185     if generator.saw_warnings:
186         print_missing_api(generator)
187     return generator.saw_warnings
188
189 configure_logging()
190
191 # We need to add the JavaScriptCore build directory to the PKG_CONFIG_PATH
192 # so that pkgconfig can properly resolve the libjavascriptcore dependency.
193 pkg_config_path = os.environ.get("PKG_CONFIG_PATH")
194 os.environ['PKG_CONFIG_PATH'] = common.build_path('Source', 'JavaScriptCore')
195 if pkg_config_path:
196     os.environ['PKG_CONFIG_PATH'] += ':' + pkg_config_path
197
198 # Newer versions of glib have deprecated g_type_init, so we need to disable
199 # that warning when running gtkdoc-scanobj by overriding the CFLAGS we use
200 # to compile it.
201 cflags = os.environ.get('CFLAGS', '')
202 cflags += ' -DGLIB_VERSION_MIN_REQUIRED=GLIB_VERSION_2_32'
203 os.environ['CFLAGS'] = cflags
204
205 # Clang can be noisy, throwing unnecessary warnings for unused arguments.
206 if os.environ.get('CC') == "clang":
207     os.environ['CFLAGS'] += ' -Qunused-arguments'
208
209 saw_webkit1_warnings = saw_webkit2_warnings = False
210 wk2_pkg_config_path = common.build_path('Source', 'WebKit2', 'webkit2gtk-3.0.pc')
211 wk1_pkg_config_path = common.build_path('Source', 'WebKit', 'gtk', 'webkitgtk-3.0.pc')
212 if not os.path.exists(wk1_pkg_config_path):
213     wk1_pkg_config_path = common.build_path('Source', 'WebKit', 'gtk', 'webkit-1.0.pc')
214
215 if os.path.exists(wk2_pkg_config_path):
216     pkg_config_path = wk2_pkg_config_path
217 elif os.path.exists(wk1_pkg_config_path):
218     pkg_config_path = wk1_pkg_config_path
219 generator = gtkdoc.PkgConfigGTKDoc(pkg_config_path, get_webkitdom_options())
220 if '--rebase' not in sys.argv:
221     print("\nGenerating WebKitDOM documentation...")
222     saw_webkitdom_warnings = generate_doc(generator)
223 else:
224     print("\nRebasing WebKitDOM documentation...")
225     try:
226         generator.rebase_installed_docs()
227     except Exception:
228         print("Rebase did not happen, likely no documentation is present.")
229
230 pkg_config_path = wk1_pkg_config_path
231 if os.path.exists(pkg_config_path):
232     options = get_webkit1_options(common.gtk_version_of_pkg_config_file(pkg_config_path))
233     generator = gtkdoc.PkgConfigGTKDoc(pkg_config_path, options)
234     if '--rebase' not in sys.argv:
235         print("Generating WebKit1 documentation...")
236         saw_webkit1_warnings = generate_doc(generator)
237     else:
238         print("Rebasing WebKit1 documentation...")
239         try:
240             generator.rebase_installed_docs()
241         except Exception:
242             print("Rebase did not happen, likely no documentation is present.")
243
244 # WebKit2 might not be enabled, so check for the pkg-config file before building documentation.
245 pkg_config_path = wk2_pkg_config_path
246 if os.path.exists(pkg_config_path):
247     generator = gtkdoc.PkgConfigGTKDoc(pkg_config_path, get_webkit2_options())
248     if '--rebase' not in sys.argv:
249         print("\nGenerating WebKit2 documentation...")
250         saw_webkit2_warnings = generate_doc(generator)
251     else:
252         print("\nRebasing WebKit2 documentation...")
253         try:
254             generator.rebase_installed_docs()
255         except Exception:
256             print("Rebase did not happen, likely no documentation is present.")
257
258 sys.exit(saw_webkit1_warnings or saw_webkit2_warnings)