blob: 48ae72399aa3ec75e96df05d6a0fd888d4a908fd [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 {
Anton Hansson867f94c2021-05-05 10:32:31 +010059 name: "android-non-updatable-doc-stubs-defaults",
60 defaults: ["android-non-updatable-stubs-defaults"],
61 srcs: [
62 // No longer part of the stubs, but are included in the docs.
63 "test-base/src/**/*.java",
64 "test-mock/src/**/*.java",
65 "test-runner/src/**/*.java",
66 ],
67 libs: framework_docs_only_libs,
68 create_doc_stubs: true,
69 write_sdk_values: true,
70}
71
72stubs_defaults {
Jiyong Park7fb4b182019-12-20 14:35:43 +090073 name: "framework-doc-stubs-default",
74 srcs: [
Anton Hansson867f94c2021-05-05 10:32:31 +010075 ":android-non-updatable-stub-sources",
Anton Hansson35c0b092021-03-30 10:46:48 +010076
77 // Module sources
Paul Duffin404b26a2020-09-16 14:26:47 +010078 ":art.module.public.api{.public.stubs.source}",
Paul Duffine55d4e32020-05-14 17:55:46 +010079 ":conscrypt.module.public.api{.public.stubs.source}",
Anton Hansson35c0b092021-03-30 10:46:48 +010080 ":framework-appsearch-sources",
81 ":framework-connectivity-sources",
82 ":framework-graphics-srcs",
83 ":framework-mediaprovider-sources",
84 ":framework-permission-sources",
85 ":framework-permission-s-sources",
86 ":framework-scheduling-sources",
87 ":framework-sdkextensions-sources",
88 ":framework-statsd-sources",
89 ":framework-tethering-srcs",
90 ":framework-wifi-updatable-sources",
Paul Duffin5a4e8f22020-11-25 15:45:43 +000091 ":i18n.module.public.api{.public.stubs.source}",
Anton Hansson35c0b092021-03-30 10:46:48 +010092 ":ike-srcs",
93 ":updatable-media-srcs",
94
95 // No longer part of the stubs, but are included in the docs.
Anton Hansson2e25fdc2021-05-10 12:40:05 +010096 ":android-test-base-sources",
97 ":android-test-mock-sources",
98 ":android-test-runner-sources",
Jiyong Park7fb4b182019-12-20 14:35:43 +090099 ],
100 libs: framework_docs_only_libs,
101 create_doc_stubs: true,
102 annotations_enabled: true,
Anton Hansson76ac4cc2021-05-05 19:22:52 +0100103 filter_packages: packages_to_document,
Jiyong Park7fb4b182019-12-20 14:35:43 +0900104 api_levels_annotations_enabled: true,
105 api_levels_annotations_dirs: [
106 "sdk-dir",
107 "api-versions-jars-dir",
108 ],
Anton Hanssonf68ddea2020-05-02 17:49:26 +0100109 previous_api: ":android.api.public.latest",
Jiyong Park7fb4b182019-12-20 14:35:43 +0900110 merge_annotations_dirs: [
111 "metalava-manual",
112 ],
Ytai Ben-Tsvida7c21e2020-09-16 13:04:31 -0700113 // TODO(b/169090544): remove below aidl includes.
114 aidl: {
115 local_include_dirs: ["media/aidl"],
Jeff Sharkey75d4f932021-07-26 15:41:01 -0600116 include_dirs: [
117 "frameworks/av/aidl",
118 "frameworks/native/libs/permission/aidl",
119 ],
Ytai Ben-Tsvida7c21e2020-09-16 13:04:31 -0700120 },
Jiyong Park7fb4b182019-12-20 14:35:43 +0900121}
122
123droidstubs {
Anton Hansson867f94c2021-05-05 10:32:31 +0100124 name: "android-non-updatable-doc-stubs",
125 defaults: ["android-non-updatable-doc-stubs-defaults"],
126 args: metalava_framework_docs_args,
127}
128
129droidstubs {
130 name: "android-non-updatable-doc-stubs-system",
131 defaults: ["android-non-updatable-doc-stubs-defaults"],
132 args: metalava_framework_docs_args +
133 " --show-annotation android.annotation.SystemApi\\(client=android.annotation.SystemApi.Client.PRIVILEGED_APPS\\) ",
134}
135
136droidstubs {
Jiyong Park7fb4b182019-12-20 14:35:43 +0900137 name: "framework-doc-stubs",
138 defaults: ["framework-doc-stubs-default"],
139 arg_files: [
140 "core/res/AndroidManifest.xml",
141 ],
Anton Hansson26c843f2021-05-05 11:11:57 +0100142 args: metalava_framework_docs_args,
Jiyong Park7fb4b182019-12-20 14:35:43 +0900143 write_sdk_values: true,
144}
145
146droidstubs {
147 name: "framework-doc-system-stubs",
148 defaults: ["framework-doc-stubs-default"],
149 arg_files: [
150 "core/res/AndroidManifest.xml",
151 ],
Anton Hansson121ccbc2020-12-17 14:56:06 +0000152 args: metalava_framework_docs_args +
Anton Hansson121ccbc2020-12-17 14:56:06 +0000153 " --show-annotation android.annotation.SystemApi\\(client=android.annotation.SystemApi.Client.PRIVILEGED_APPS\\) ",
Jiyong Park7fb4b182019-12-20 14:35:43 +0900154 write_sdk_values: true,
satayevbc7c83e2021-06-29 22:27:06 +0100155 api_levels_sdk_type: "system",
Jiyong Park7fb4b182019-12-20 14:35:43 +0900156}
157
158/////////////////////////////////////////////////////////////////////
159// API docs are created from the generated stub source files
160// using droiddoc
161/////////////////////////////////////////////////////////////////////
162
163framework_docs_only_args = " -android -manifest $(location core/res/AndroidManifest.xml) " +
164 "-werror -lerror -hide 111 -hide 113 -hide 125 -hide 126 -hide 127 -hide 128 " +
165 "-overview $(location core/java/overview.html) " +
166 // Federate Support Library references against local API file.
167 "-federate SupportLib https://developer.android.com " +
168 "-federationapi SupportLib $(location :current-support-api) " +
169 // Federate Support Library references against local API file.
170 "-federate AndroidX https://developer.android.com " +
171 "-federationapi AndroidX $(location :current-androidx-api) "
172
173doc_defaults {
174 name: "framework-docs-default",
Artur Satayevffd7f952020-01-13 16:16:27 +0000175 libs: framework_docs_only_libs + [
176 "stub-annotations",
177 "unsupportedappusage",
178 ],
Jiyong Park7fb4b182019-12-20 14:35:43 +0900179 html_dirs: [
180 "docs/html",
181 ],
182 knowntags: [
183 "docs/knowntags.txt",
Paul Duffin8c083f62020-09-08 20:22:49 +0100184 ":art.module.public.api{.doctags}",
Jiyong Park7fb4b182019-12-20 14:35:43 +0900185 ],
186 custom_template: "droiddoc-templates-sdk",
187 resourcesdir: "docs/html/reference/images/",
188 resourcesoutdir: "reference/android/images/",
189 hdf: [
190 "dac true",
191 "sdk.codename O",
192 "sdk.preview.version 1",
193 "sdk.version 7.0",
194 "sdk.rel.id 1",
195 "sdk.preview 0",
196 ],
197 arg_files: [
198 "core/res/AndroidManifest.xml",
199 "core/java/overview.html",
200 ":current-support-api",
201 ":current-androidx-api",
202 ],
Ytai Ben-Tsvida7c21e2020-09-16 13:04:31 -0700203 // TODO(b/169090544): remove below aidl includes.
204 aidl: {
205 local_include_dirs: ["media/aidl"],
Jeff Sharkey75d4f932021-07-26 15:41:01 -0600206 include_dirs: [
207 "frameworks/av/aidl",
208 "frameworks/native/libs/permission/aidl",
209 ],
Ytai Ben-Tsvida7c21e2020-09-16 13:04:31 -0700210 },
Jiyong Park7fb4b182019-12-20 14:35:43 +0900211}
212
213doc_defaults {
214 name: "framework-dokka-docs-default",
Jiyong Park7fb4b182019-12-20 14:35:43 +0900215}
216
217droiddoc {
218 name: "doc-comment-check-docs",
219 defaults: ["framework-docs-default"],
220 srcs: [
221 ":framework-doc-stubs",
222 ],
223 args: framework_docs_only_args + " -referenceonly -parsecomments",
224 installable: false,
225}
226
227droiddoc {
228 name: "offline-sdk-docs",
229 defaults: ["framework-docs-default"],
230 srcs: [
231 ":framework-doc-stubs",
232 ],
233 hdf: [
234 "android.whichdoc offline",
235 ],
atrostb1ee27b2020-02-03 11:03:16 +0000236 compat_config: ":global-compat-config",
Jiyong Park7fb4b182019-12-20 14:35:43 +0900237 proofread_file: "offline-sdk-docs-proofrerad.txt",
238 args: framework_docs_only_args + " -offlinemode -title \"Android SDK\"",
239 static_doc_index_redirect: "docs/docs-preview-index.html",
240}
241
242droiddoc {
243 // Please sync with android-api-council@ before making any changes for the name property below.
244 // Since there's cron jobs that fetch offline-sdk-referenceonly-docs-docs.zip periodically.
245 // See b/116221385 for reference.
246 name: "offline-sdk-referenceonly-docs",
247 defaults: ["framework-docs-default"],
248 srcs: [
249 ":framework-doc-stubs",
250 ],
251 hdf: [
252 "android.whichdoc offline",
253 ],
254 proofread_file: "offline-sdk-referenceonly-docs-proofrerad.txt",
255 args: framework_docs_only_args + " -offlinemode -title \"Android SDK\" -referenceonly",
256 static_doc_index_redirect: "docs/docs-documentation-redirect.html",
257 static_doc_properties: "docs/source.properties",
258}
259
260droiddoc {
261 // Please sync with android-api-council@ before making any changes for the name property below.
262 // Since there's cron jobs that fetch offline-system-sdk-referenceonly-docs-docs.zip periodically.
263 // See b/116221385 for reference.
264 name: "offline-system-sdk-referenceonly-docs",
265 defaults: ["framework-docs-default"],
266 srcs: [
267 ":framework-doc-system-stubs",
268 ],
269 hdf: [
270 "android.whichdoc offline",
271 ],
272 proofread_file: "offline-system-sdk-referenceonly-docs-proofrerad.txt",
273 args: framework_docs_only_args + " -hide 101 -hide 104 -hide 108" +
274 " -offlinemode -title \"Android System SDK\" -referenceonly",
275 static_doc_index_redirect: "docs/docs-documentation-redirect.html",
276 static_doc_properties: "docs/source.properties",
277}
278
279droiddoc {
280 name: "online-sdk-docs",
281 defaults: ["framework-docs-default"],
282 srcs: [
283 ":framework-doc-stubs",
284 ],
285 hdf: [
286 "android.whichdoc online",
287 "android.hasSamples true",
288 ],
289 proofread_file: "online-sdk-docs-proofrerad.txt",
290 args: framework_docs_only_args +
291 " -toroot / -samplegroup Admin " +
292 " -samplegroup Background " +
293 " -samplegroup Connectivity " +
294 " -samplegroup Content " +
295 " -samplegroup Input " +
296 " -samplegroup Media " +
297 " -samplegroup Notification " +
298 " -samplegroup RenderScript " +
299 " -samplegroup Security " +
300 " -samplegroup Sensors " +
301 " -samplegroup System " +
302 " -samplegroup Testing " +
303 " -samplegroup UI " +
304 " -samplegroup Views " +
305 " -samplegroup Wearable -samplesdir development/samples/browseable ",
306}
307
308droiddoc {
309 name: "online-system-api-sdk-docs",
310 defaults: ["framework-docs-default"],
311 srcs: [
312 ":framework-doc-system-stubs",
313 ],
314 hdf: [
315 "android.whichdoc online",
316 "android.hasSamples true",
317 ],
318 proofread_file: "online-system-api-sdk-docs-proofrerad.txt",
319 args: framework_docs_only_args +
320 " -referenceonly " +
321 " -title \"Android SDK - Including system APIs.\" " +
322 " -hide 101 " +
323 " -hide 104 " +
324 " -hide 108 " +
325 " -toroot / -samplegroup Admin " +
326 " -samplegroup Background " +
327 " -samplegroup Connectivity " +
328 " -samplegroup Content " +
329 " -samplegroup Input " +
330 " -samplegroup Media " +
331 " -samplegroup Notification " +
332 " -samplegroup RenderScript " +
333 " -samplegroup Security " +
334 " -samplegroup Sensors " +
335 " -samplegroup System " +
336 " -samplegroup Testing " +
337 " -samplegroup UI " +
338 " -samplegroup Views " +
339 " -samplegroup Wearable -samplesdir development/samples/browseable ",
340 installable: false,
341}
342
343droiddoc {
344 name: "ds-docs-java",
345 defaults: ["framework-docs-default"],
346 srcs: [
347 ":framework-doc-stubs",
348 ],
349 hdf: [
350 "android.whichdoc online",
351 "android.hasSamples true",
352 ],
353 proofread_file: "ds-docs-proofrerad.txt",
354 args: framework_docs_only_args +
355 " -toroot / -yamlV2 -metalavaApiSince -samplegroup Admin " +
356 " -samplegroup Background " +
357 " -samplegroup Connectivity " +
358 " -samplegroup Content " +
359 " -samplegroup Input " +
360 " -samplegroup Media " +
361 " -samplegroup Notification " +
362 " -samplegroup RenderScript " +
363 " -samplegroup Security " +
364 " -samplegroup Sensors " +
365 " -samplegroup System " +
366 " -samplegroup Testing " +
367 " -samplegroup UI " +
368 " -samplegroup Views " +
369 " -samplegroup Wearable -devsite -samplesdir development/samples/browseable ",
370}
371
372droiddoc {
373 name: "ds-docs-kt",
374 defaults: ["framework-dokka-docs-default"],
375 srcs: [
376 ":framework-doc-stubs",
377 ],
378 args: "-noJdkLink -links https://kotlinlang.org/api/latest/jvm/stdlib/^external/dokka/package-list " +
Dan Willemsencece97c2020-04-20 22:32:45 -0700379 "-noStdlibLink",
Jiyong Park7fb4b182019-12-20 14:35:43 +0900380 proofread_file: "ds-dokka-proofread.txt",
381 dokka_enabled: true,
382}
383
384java_genrule {
385 name: "ds-docs",
386 tools: [
387 "zip2zip",
388 "merge_zips",
389 ],
390 srcs: [
391 ":ds-docs-java{.docs.zip}",
392 ":ds-docs-kt{.docs.zip}",
393 ],
394 out: ["ds-docs.zip"],
395 dist: {
396 targets: ["docs"],
397 },
398 cmd: "$(location zip2zip) -i $(location :ds-docs-kt{.docs.zip}) -o $(genDir)/ds-docs-kt-moved.zip **/*:en/reference/kotlin && " +
Dan Willemsencece97c2020-04-20 22:32:45 -0700399 "$(location merge_zips) $(out) $(location :ds-docs-java{.docs.zip}) $(genDir)/ds-docs-kt-moved.zip",
Jiyong Park7fb4b182019-12-20 14:35:43 +0900400}
401
402java_genrule {
403 name: "ds-docs-switched",
404 tools: [
405 "switcher4",
406 "soong_zip",
407 ],
408 srcs: [
409 ":ds-docs-java{.docs.zip}",
410 ":ds-docs-kt{.docs.zip}",
411 ],
412 out: ["ds-docs-switched.zip"],
413 dist: {
414 targets: ["docs"],
415 },
Colin Crossa2410eb2020-02-26 13:04:57 -0800416 cmd: "unzip -q $(location :ds-docs-java{.docs.zip}) -d $(genDir) && " +
Dan Willemsencece97c2020-04-20 22:32:45 -0700417 "unzip -q $(location :ds-docs-kt{.docs.zip}) -d $(genDir)/en/reference/kotlin && " +
418 "SWITCHER=$$(cd $$(dirname $(location switcher4)) && pwd)/$$(basename $(location switcher4)) && " +
419 "(cd $(genDir)/en/reference && $$SWITCHER --work platform) > /dev/null && " +
420 "$(location soong_zip) -o $(out) -C $(genDir) -D $(genDir)",
Jiyong Park7fb4b182019-12-20 14:35:43 +0900421}
422
423droiddoc {
424 name: "ds-static-docs",
425 defaults: ["framework-docs-default"],
426 srcs: [
427 ":framework-doc-stubs",
428 ],
429 hdf: [
430 "android.whichdoc online",
431 ],
Jiyong Park7fb4b182019-12-20 14:35:43 +0900432 args: framework_docs_only_args +
433 " -staticonly " +
434 " -toroot / " +
435 " -devsite " +
436 " -ignoreJdLinks ",
437}
438
439droiddoc {
440 name: "ds-ref-navtree-docs",
441 defaults: ["framework-docs-default"],
442 srcs: [
443 ":framework-doc-stubs",
444 ],
445 hdf: [
446 "android.whichdoc online",
447 ],
Jiyong Park7fb4b182019-12-20 14:35:43 +0900448 args: framework_docs_only_args +
449 " -toroot / " +
450 " -atLinksNavtree " +
451 " -navtreeonly ",
452}
453
454droiddoc {
455 name: "online-sdk-dev-docs",
456 defaults: ["framework-docs-default"],
457 srcs: [
458 ":framework-doc-stubs",
459 ],
460 hdf: [
461 "android.whichdoc online",
462 "android.hasSamples true",
463 ],
464 proofread_file: "online-sdk-dev-docs-proofrerad.txt",
465 args: framework_docs_only_args +
466 " -toroot / -samplegroup Admin " +
467 " -samplegroup Background " +
468 " -samplegroup Connectivity " +
469 " -samplegroup Content " +
470 " -samplegroup Input " +
471 " -samplegroup Media " +
472 " -samplegroup Notification " +
473 " -samplegroup RenderScript " +
474 " -samplegroup Security " +
475 " -samplegroup Sensors " +
476 " -samplegroup System " +
477 " -samplegroup Testing " +
478 " -samplegroup UI " +
479 " -samplegroup Views " +
480 " -samplegroup Wearable -samplesdir development/samples/browseable ",
481}
482
483droiddoc {
484 name: "hidden-docs",
485 defaults: ["framework-docs-default"],
486 srcs: [
487 ":framework-doc-stubs",
488 ],
489 proofread_file: "hidden-docs-proofrerad.txt",
490 args: framework_docs_only_args +
491 " -referenceonly " +
492 " -title \"Android SDK - Including hidden APIs.\"",
493}