blob: 90df19a9491aca0eed695caea7d08b9d842fe858 [file] [log] [blame]
Jiyong Park7fb4b182019-12-20 14:35:43 +09001// Copyright (C) 2019 The Android Open Source Project
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7// http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15// How API docs are generated:
16//
17// raw source files --(metalava)--> stub source files --(doclava)--> API doc
18//
19// The metalava conversion is done by droidstub modules framework-doc-*-stubs.
20// The API doc generation is done by the various droiddoc modules each of which
21// is for different format.
22
23/////////////////////////////////////////////////////////////////////
24// stub source files are generated using metalava
25/////////////////////////////////////////////////////////////////////
26
27framework_docs_only_libs = [
28 "voip-common",
29 "android.test.mock",
30 "android-support-annotations",
31 "android-support-compat",
32 "android-support-core-ui",
33 "android-support-core-utils",
34 "android-support-design",
35 "android-support-dynamic-animation",
36 "android-support-exifinterface",
37 "android-support-fragment",
38 "android-support-media-compat",
39 "android-support-percent",
40 "android-support-transition",
41 "android-support-v7-cardview",
42 "android-support-v7-gridlayout",
43 "android-support-v7-mediarouter",
44 "android-support-v7-palette",
45 "android-support-v7-preference",
46 "android-support-v13",
47 "android-support-v14-preference",
48 "android-support-v17-leanback",
49 "android-support-vectordrawable",
50 "android-support-animatedvectordrawable",
51 "android-support-v7-appcompat",
52 "android-support-v7-recyclerview",
53 "android-support-v8-renderscript",
54 "android-support-multidex",
55 "android-support-multidex-instrumentation",
56]
57
58stubs_defaults {
59 name: "framework-doc-stubs-default",
60 srcs: [
61 ":framework-mime-sources",
62 ":framework-non-updatable-sources",
63 ":framework-updatable-sources",
64 "core/java/**/*.logtags",
65 "test-base/src/**/*.java",
66 ":opt-telephony-srcs",
67 ":opt-net-voip-srcs",
Paul Duffin37c10f02020-03-26 15:33:48 +000068 ":art-module-public-api-stubs-source",
Paul Duffinf0255012020-04-09 10:04:14 +010069 ":conscrypt.module.public.api.stubs.source",
Paul Duffin37c10f02020-03-26 15:33:48 +000070 ":android_icu4j_public_api_files",
Jiyong Park7fb4b182019-12-20 14:35:43 +090071 "test-mock/src/**/*.java",
72 "test-runner/src/**/*.java",
73 ],
74 libs: framework_docs_only_libs,
75 create_doc_stubs: true,
76 annotations_enabled: true,
77 api_levels_annotations_enabled: true,
78 api_levels_annotations_dirs: [
79 "sdk-dir",
80 "api-versions-jars-dir",
81 ],
Anton Hansson48ee95e2020-05-02 17:49:26 +010082 previous_api: ":android.api.public.latest",
Jiyong Park7fb4b182019-12-20 14:35:43 +090083 merge_annotations_dirs: [
84 "metalava-manual",
85 ],
86}
87
88droidstubs {
89 name: "framework-doc-stubs",
90 defaults: ["framework-doc-stubs-default"],
91 arg_files: [
92 "core/res/AndroidManifest.xml",
93 ],
94 args: metalava_framework_docs_args,
95 write_sdk_values: true,
96}
97
98droidstubs {
99 name: "framework-doc-system-stubs",
100 defaults: ["framework-doc-stubs-default"],
101 arg_files: [
102 "core/res/AndroidManifest.xml",
103 ],
Jiyong Park92514d52020-05-02 22:05:50 +0900104 args: metalava_framework_docs_args + " --show-annotation android.annotation.SystemApi\\(client=android.annotation.SystemApi.Client.PRIVILEGED_APPS\\) ",
Jiyong Park7fb4b182019-12-20 14:35:43 +0900105 write_sdk_values: true,
106}
107
108/////////////////////////////////////////////////////////////////////
109// API docs are created from the generated stub source files
110// using droiddoc
111/////////////////////////////////////////////////////////////////////
112
113framework_docs_only_args = " -android -manifest $(location core/res/AndroidManifest.xml) " +
114 "-werror -lerror -hide 111 -hide 113 -hide 125 -hide 126 -hide 127 -hide 128 " +
115 "-overview $(location core/java/overview.html) " +
116 // Federate Support Library references against local API file.
117 "-federate SupportLib https://developer.android.com " +
118 "-federationapi SupportLib $(location :current-support-api) " +
119 // Federate Support Library references against local API file.
120 "-federate AndroidX https://developer.android.com " +
121 "-federationapi AndroidX $(location :current-androidx-api) "
122
123doc_defaults {
124 name: "framework-docs-default",
Artur Satayevffd7f952020-01-13 16:16:27 +0000125 libs: framework_docs_only_libs + [
126 "stub-annotations",
127 "unsupportedappusage",
128 ],
Jiyong Park7fb4b182019-12-20 14:35:43 +0900129 html_dirs: [
130 "docs/html",
131 ],
132 knowntags: [
133 "docs/knowntags.txt",
134 ":known-oj-tags",
135 ],
136 custom_template: "droiddoc-templates-sdk",
137 resourcesdir: "docs/html/reference/images/",
138 resourcesoutdir: "reference/android/images/",
139 hdf: [
140 "dac true",
141 "sdk.codename O",
142 "sdk.preview.version 1",
143 "sdk.version 7.0",
144 "sdk.rel.id 1",
145 "sdk.preview 0",
146 ],
147 arg_files: [
148 "core/res/AndroidManifest.xml",
149 "core/java/overview.html",
150 ":current-support-api",
151 ":current-androidx-api",
152 ],
153 create_stubs: false,
154}
155
156doc_defaults {
157 name: "framework-dokka-docs-default",
158 create_stubs: false,
159}
160
161droiddoc {
162 name: "doc-comment-check-docs",
163 defaults: ["framework-docs-default"],
164 srcs: [
165 ":framework-doc-stubs",
166 ],
167 args: framework_docs_only_args + " -referenceonly -parsecomments",
168 installable: false,
169}
170
171droiddoc {
172 name: "offline-sdk-docs",
173 defaults: ["framework-docs-default"],
174 srcs: [
175 ":framework-doc-stubs",
176 ],
177 hdf: [
178 "android.whichdoc offline",
179 ],
atrostb1ee27b2020-02-03 11:03:16 +0000180 compat_config: ":global-compat-config",
Jiyong Park7fb4b182019-12-20 14:35:43 +0900181 proofread_file: "offline-sdk-docs-proofrerad.txt",
182 args: framework_docs_only_args + " -offlinemode -title \"Android SDK\"",
183 static_doc_index_redirect: "docs/docs-preview-index.html",
184}
185
186droiddoc {
187 // Please sync with android-api-council@ before making any changes for the name property below.
188 // Since there's cron jobs that fetch offline-sdk-referenceonly-docs-docs.zip periodically.
189 // See b/116221385 for reference.
190 name: "offline-sdk-referenceonly-docs",
191 defaults: ["framework-docs-default"],
192 srcs: [
193 ":framework-doc-stubs",
194 ],
195 hdf: [
196 "android.whichdoc offline",
197 ],
198 proofread_file: "offline-sdk-referenceonly-docs-proofrerad.txt",
199 args: framework_docs_only_args + " -offlinemode -title \"Android SDK\" -referenceonly",
200 static_doc_index_redirect: "docs/docs-documentation-redirect.html",
201 static_doc_properties: "docs/source.properties",
202}
203
204droiddoc {
205 // Please sync with android-api-council@ before making any changes for the name property below.
206 // Since there's cron jobs that fetch offline-system-sdk-referenceonly-docs-docs.zip periodically.
207 // See b/116221385 for reference.
208 name: "offline-system-sdk-referenceonly-docs",
209 defaults: ["framework-docs-default"],
210 srcs: [
211 ":framework-doc-system-stubs",
212 ],
213 hdf: [
214 "android.whichdoc offline",
215 ],
216 proofread_file: "offline-system-sdk-referenceonly-docs-proofrerad.txt",
217 args: framework_docs_only_args + " -hide 101 -hide 104 -hide 108" +
218 " -offlinemode -title \"Android System SDK\" -referenceonly",
219 static_doc_index_redirect: "docs/docs-documentation-redirect.html",
220 static_doc_properties: "docs/source.properties",
221}
222
223droiddoc {
224 name: "online-sdk-docs",
225 defaults: ["framework-docs-default"],
226 srcs: [
227 ":framework-doc-stubs",
228 ],
229 hdf: [
230 "android.whichdoc online",
231 "android.hasSamples true",
232 ],
233 proofread_file: "online-sdk-docs-proofrerad.txt",
234 args: framework_docs_only_args +
235 " -toroot / -samplegroup Admin " +
236 " -samplegroup Background " +
237 " -samplegroup Connectivity " +
238 " -samplegroup Content " +
239 " -samplegroup Input " +
240 " -samplegroup Media " +
241 " -samplegroup Notification " +
242 " -samplegroup RenderScript " +
243 " -samplegroup Security " +
244 " -samplegroup Sensors " +
245 " -samplegroup System " +
246 " -samplegroup Testing " +
247 " -samplegroup UI " +
248 " -samplegroup Views " +
249 " -samplegroup Wearable -samplesdir development/samples/browseable ",
250}
251
252droiddoc {
253 name: "online-system-api-sdk-docs",
254 defaults: ["framework-docs-default"],
255 srcs: [
256 ":framework-doc-system-stubs",
257 ],
258 hdf: [
259 "android.whichdoc online",
260 "android.hasSamples true",
261 ],
262 proofread_file: "online-system-api-sdk-docs-proofrerad.txt",
263 args: framework_docs_only_args +
264 " -referenceonly " +
265 " -title \"Android SDK - Including system APIs.\" " +
266 " -hide 101 " +
267 " -hide 104 " +
268 " -hide 108 " +
269 " -toroot / -samplegroup Admin " +
270 " -samplegroup Background " +
271 " -samplegroup Connectivity " +
272 " -samplegroup Content " +
273 " -samplegroup Input " +
274 " -samplegroup Media " +
275 " -samplegroup Notification " +
276 " -samplegroup RenderScript " +
277 " -samplegroup Security " +
278 " -samplegroup Sensors " +
279 " -samplegroup System " +
280 " -samplegroup Testing " +
281 " -samplegroup UI " +
282 " -samplegroup Views " +
283 " -samplegroup Wearable -samplesdir development/samples/browseable ",
284 installable: false,
285}
286
287droiddoc {
288 name: "ds-docs-java",
289 defaults: ["framework-docs-default"],
290 srcs: [
291 ":framework-doc-stubs",
292 ],
293 hdf: [
294 "android.whichdoc online",
295 "android.hasSamples true",
296 ],
297 proofread_file: "ds-docs-proofrerad.txt",
298 args: framework_docs_only_args +
299 " -toroot / -yamlV2 -metalavaApiSince -samplegroup Admin " +
300 " -samplegroup Background " +
301 " -samplegroup Connectivity " +
302 " -samplegroup Content " +
303 " -samplegroup Input " +
304 " -samplegroup Media " +
305 " -samplegroup Notification " +
306 " -samplegroup RenderScript " +
307 " -samplegroup Security " +
308 " -samplegroup Sensors " +
309 " -samplegroup System " +
310 " -samplegroup Testing " +
311 " -samplegroup UI " +
312 " -samplegroup Views " +
313 " -samplegroup Wearable -devsite -samplesdir development/samples/browseable ",
314}
315
316droiddoc {
317 name: "ds-docs-kt",
318 defaults: ["framework-dokka-docs-default"],
319 srcs: [
320 ":framework-doc-stubs",
321 ],
322 args: "-noJdkLink -links https://kotlinlang.org/api/latest/jvm/stdlib/^external/dokka/package-list " +
323 "-noStdlibLink",
324 proofread_file: "ds-dokka-proofread.txt",
325 dokka_enabled: true,
326}
327
328java_genrule {
329 name: "ds-docs",
330 tools: [
331 "zip2zip",
332 "merge_zips",
333 ],
334 srcs: [
335 ":ds-docs-java{.docs.zip}",
336 ":ds-docs-kt{.docs.zip}",
337 ],
338 out: ["ds-docs.zip"],
339 dist: {
340 targets: ["docs"],
341 },
342 cmd: "$(location zip2zip) -i $(location :ds-docs-kt{.docs.zip}) -o $(genDir)/ds-docs-kt-moved.zip **/*:en/reference/kotlin && " +
343 "$(location merge_zips) $(out) $(location :ds-docs-java{.docs.zip}) $(genDir)/ds-docs-kt-moved.zip",
344}
345
346java_genrule {
347 name: "ds-docs-switched",
348 tools: [
349 "switcher4",
350 "soong_zip",
351 ],
352 srcs: [
353 ":ds-docs-java{.docs.zip}",
354 ":ds-docs-kt{.docs.zip}",
355 ],
356 out: ["ds-docs-switched.zip"],
357 dist: {
358 targets: ["docs"],
359 },
360 cmd: "unzip $(location :ds-docs-java{.docs.zip}) -d $(genDir) && " +
361 "unzip $(location :ds-docs-kt{.docs.zip}) -d $(genDir)/en/reference/kotlin && " +
362 "SWITCHER=$$(cd $$(dirname $(location switcher4)) && pwd)/$$(basename $(location switcher4)) && " +
363 "(cd $(genDir)/en/reference && $$SWITCHER --work platform) && " +
364 "$(location soong_zip) -o $(out) -C $(genDir) -D $(genDir)",
365}
366
367droiddoc {
368 name: "ds-static-docs",
369 defaults: ["framework-docs-default"],
370 srcs: [
371 ":framework-doc-stubs",
372 ],
373 hdf: [
374 "android.whichdoc online",
375 ],
376 proofread_file: "ds-static-docs-proofrerad.txt",
377 args: framework_docs_only_args +
378 " -staticonly " +
379 " -toroot / " +
380 " -devsite " +
381 " -ignoreJdLinks ",
382}
383
384droiddoc {
385 name: "ds-ref-navtree-docs",
386 defaults: ["framework-docs-default"],
387 srcs: [
388 ":framework-doc-stubs",
389 ],
390 hdf: [
391 "android.whichdoc online",
392 ],
393 proofread_file: "ds-ref-navtree-docs-proofrerad.txt",
394 args: framework_docs_only_args +
395 " -toroot / " +
396 " -atLinksNavtree " +
397 " -navtreeonly ",
398}
399
400droiddoc {
401 name: "online-sdk-dev-docs",
402 defaults: ["framework-docs-default"],
403 srcs: [
404 ":framework-doc-stubs",
405 ],
406 hdf: [
407 "android.whichdoc online",
408 "android.hasSamples true",
409 ],
410 proofread_file: "online-sdk-dev-docs-proofrerad.txt",
411 args: framework_docs_only_args +
412 " -toroot / -samplegroup Admin " +
413 " -samplegroup Background " +
414 " -samplegroup Connectivity " +
415 " -samplegroup Content " +
416 " -samplegroup Input " +
417 " -samplegroup Media " +
418 " -samplegroup Notification " +
419 " -samplegroup RenderScript " +
420 " -samplegroup Security " +
421 " -samplegroup Sensors " +
422 " -samplegroup System " +
423 " -samplegroup Testing " +
424 " -samplegroup UI " +
425 " -samplegroup Views " +
426 " -samplegroup Wearable -samplesdir development/samples/browseable ",
427}
428
429droiddoc {
430 name: "hidden-docs",
431 defaults: ["framework-docs-default"],
432 srcs: [
433 ":framework-doc-stubs",
434 ],
435 proofread_file: "hidden-docs-proofrerad.txt",
436 args: framework_docs_only_args +
437 " -referenceonly " +
438 " -title \"Android SDK - Including hidden APIs.\"",
439}
440