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