5af2fc1860ead930c2974148bb2e0cb1709f3c0a
[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 get_webkit2_options():
76     def derived_sources_path(*args):
77         return common.build_path(*(('DerivedSources', 'WebKit2') + args))
78     def src_path(*args):
79         return common.top_level_path(*(('Source', 'WebKit2', 'UIProcess', 'API', 'gtk') + args))
80
81     xref_deps = get_common_xref_deps().copy()
82     xref_deps.update({
83         'gtk+-3.0' : ['gtk3', 'gdk3']
84     })
85
86     options = get_common_options().copy()
87     options.update({
88         'module_name' : 'webkit2gtk',
89         'doc_dir' : src_path('docs'),
90         'output_dir' : common.build_path('Documentation', 'webkit2gtk'),
91         'source_dirs' : [src_path(), derived_sources_path('webkit2gtk', 'webkit2')],
92         'cflags' : ' -I' + derived_sources_path('webkit2gtk', 'include') + \
93                    ' -I' + derived_sources_path('webkit2gtk') + \
94                    ' -I' + derived_sources_path('include') + \
95                    ' -I' + common.top_level_path('Source') + \
96                    ' -I' + src_path(),
97         'cross_reference_deps' : get_gtkdoc_module_paths(xref_deps),
98         'ignored_files': glob.glob(src_path('*Private.h')) + \
99                          glob.glob(src_path('*Client*')) + \
100                          glob.glob(src_path('WebKit2GtkAuthenticationDialog.*')) + \
101                          glob.glob(src_path('WebKitGeolocationProvider.*')) + \
102                          glob.glob(src_path('WebKitTextChecker.*')) + \
103                          glob.glob(src_path('WebKitWebViewBaseAccessible.*')) + \
104                          glob.glob(src_path('WebViewBaseInputMethodFilter.*')) + \
105                          glob.glob(derived_sources_path('webkit2gtk', 'webkit2', 'WebKitMarshal.*')) + \
106                          glob.glob(derived_sources_path('webkit2gtk', 'webkit2', 'WebKitEnumTypes.*')) + \
107                          glob.glob(src_path('tests/*.h'))
108     })
109     return options
110
111 def get_webkit1_options(gtk_version):
112     def src_path(*args):
113         return common.top_level_path(*(('Source', 'WebKit', 'gtk') + args))
114
115     xref_deps = get_common_xref_deps().copy()
116     if gtk_version == 3:
117         xref_deps.update({
118                 'gtk+-3.0' : ['gtk3', 'gdk3']
119         })
120     else:
121         xref_deps.update({
122                 'gtk+-2.0' : ['gtk', 'gdk']
123         })
124
125     options = get_common_options().copy()
126     options.update({
127         'module_name' : 'webkitgtk',
128         'doc_dir' : src_path('docs'),
129         'output_dir' : common.build_path('Documentation', 'webkitgtk'),
130         'source_dirs' : [src_path('webkit'), common.build_path('Source', 'WebKit', 'gtk', 'webkit')],
131         'cflags' : ' -I' + common.build_path('WebKit', 'gtk') + \
132                    ' -I' + common.build_path('DerivedSources') + \
133                    ' -I' + src_path() + \
134                    ' -I' + common.top_level_path('Source') + \
135                    ' -I' + common.top_level_path('Source', 'JavaScriptCore', 'ForwardingHeaders'),
136         'cross_reference_deps' : get_gtkdoc_module_paths(xref_deps),
137         'ignored_files': glob.glob(src_path('webkit', '*private.*')) + \
138                          glob.glob(src_path('webkit', 'webkitspellcheckerenchant.*'))
139     })
140     return options
141
142 def print_missing_api(generator):
143     missing_api = generator.api_missing_documentation()
144     if not missing_api:
145         return
146     print("\nThe following API are missing documentation:")
147     for api in missing_api:
148         print("\t%s" % api)
149
150 def generate_doc(generator):
151     generator.generate(html='--skip-html' not in sys.argv)
152     if generator.saw_warnings:
153         print_missing_api(generator)
154     return generator.saw_warnings
155
156 configure_logging()
157
158 # We need to add the JavaScriptCore build directory to the PKG_CONFIG_PATH
159 # so that pkgconfig can properly resolve the libjavascriptcore dependency.
160 pkg_config_path = os.environ.get("PKG_CONFIG_PATH")
161 os.environ['PKG_CONFIG_PATH'] = common.build_path('Source', 'JavaScriptCore')
162 if pkg_config_path:
163     os.environ['PKG_CONFIG_PATH'] += ':' + pkg_config_path
164
165 # Newer versions of glib have deprecated g_type_init, so we need to disable
166 # that warning when running gtkdoc-scanobj by overriding the CFLAGS we use
167 # to compile it.
168 cflags = os.environ.get('CFLAGS', '')
169 cflags += ' -DGLIB_VERSION_MIN_REQUIRED=GLIB_VERSION_2_32'
170 os.environ['CFLAGS'] = cflags
171
172 saw_webkit1_warnings = saw_webkit2_warnings = False
173
174 pkg_config_path = common.build_path('Source', 'WebKit', 'gtk', 'webkitgtk-3.0.pc')
175 if not os.path.exists(pkg_config_path):
176     pkg_config_path = common.build_path('Source', 'WebKit', 'gtk', 'webkit-1.0.pc')
177 if os.path.exists(pkg_config_path):
178     options = get_webkit1_options(common.gtk_version_of_pkg_config_file(pkg_config_path))
179     generator = gtkdoc.PkgConfigGTKDoc(pkg_config_path, options)
180     if '--rebase' not in sys.argv:
181         print("Generating WebKit1 documentation...")
182         saw_webkit1_warnings = generate_doc(generator)
183     else:
184         print("Rebasing WebKit1 documentation...")
185         try:
186             generator.rebase_installed_docs()
187         except Exception:
188             print("Rebase did not happen, likely no documentation is present.")
189
190 # WebKit2 might not be enabled, so check for the pkg-config file before building documentation.
191 pkg_config_path = common.build_path('Source', 'WebKit2', 'webkit2gtk-3.0.pc')
192 if os.path.exists(pkg_config_path):
193     generator = gtkdoc.PkgConfigGTKDoc(pkg_config_path, get_webkit2_options())
194     if '--rebase' not in sys.argv:
195         print("\nGenerating WebKit2 documentation...")
196         saw_webkit2_warnings = generate_doc(generator)
197     else:
198         print("\nRebasing WebKit2 documentation...")
199         try:
200             generator.rebase_installed_docs()
201         except Exception:
202             print("Rebase did not happen, likely no documentation is present.")
203
204 sys.exit(saw_webkit1_warnings or saw_webkit2_warnings)