blob: e373db66925f244b02c8e4ba48f6d5f11ee4256b [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",
68 ":core-current-stubs-source",
69 ":core_public_api_files",
70 "test-mock/src/**/*.java",
71 "test-runner/src/**/*.java",
72 ],
73 libs: framework_docs_only_libs,
74 create_doc_stubs: true,
75 annotations_enabled: true,
76 api_levels_annotations_enabled: true,
77 api_levels_annotations_dirs: [
78 "sdk-dir",
79 "api-versions-jars-dir",
80 ],
81 previous_api: ":last-released-public-api",
82 merge_annotations_dirs: [
83 "metalava-manual",
84 ],
85}
86
87droidstubs {
88 name: "framework-doc-stubs",
89 defaults: ["framework-doc-stubs-default"],
90 arg_files: [
91 "core/res/AndroidManifest.xml",
92 ],
93 args: metalava_framework_docs_args,
94 write_sdk_values: true,
95}
96
97droidstubs {
98 name: "framework-doc-system-stubs",
99 defaults: ["framework-doc-stubs-default"],
100 arg_files: [
101 "core/res/AndroidManifest.xml",
102 ],
103 args: metalava_framework_docs_args + " --show-annotation android.annotation.SystemApi\\(client=android.annotation.SystemApi.Client.PRIVILEGED_APPS,process=android.annotation.SystemApi.Process.ALL\\) ",
104 write_sdk_values: true,
105}
106
107/////////////////////////////////////////////////////////////////////
108// API docs are created from the generated stub source files
109// using droiddoc
110/////////////////////////////////////////////////////////////////////
111
112framework_docs_only_args = " -android -manifest $(location core/res/AndroidManifest.xml) " +
113 "-werror -lerror -hide 111 -hide 113 -hide 125 -hide 126 -hide 127 -hide 128 " +
114 "-overview $(location core/java/overview.html) " +
115 // Federate Support Library references against local API file.
116 "-federate SupportLib https://developer.android.com " +
117 "-federationapi SupportLib $(location :current-support-api) " +
118 // Federate Support Library references against local API file.
119 "-federate AndroidX https://developer.android.com " +
120 "-federationapi AndroidX $(location :current-androidx-api) "
121
122doc_defaults {
123 name: "framework-docs-default",
124 libs: framework_docs_only_libs +
125 ["stub-annotations"],
126 html_dirs: [
127 "docs/html",
128 ],
129 knowntags: [
130 "docs/knowntags.txt",
131 ":known-oj-tags",
132 ],
133 custom_template: "droiddoc-templates-sdk",
134 resourcesdir: "docs/html/reference/images/",
135 resourcesoutdir: "reference/android/images/",
136 hdf: [
137 "dac true",
138 "sdk.codename O",
139 "sdk.preview.version 1",
140 "sdk.version 7.0",
141 "sdk.rel.id 1",
142 "sdk.preview 0",
143 ],
144 arg_files: [
145 "core/res/AndroidManifest.xml",
146 "core/java/overview.html",
147 ":current-support-api",
148 ":current-androidx-api",
149 ],
150 create_stubs: false,
151}
152
153doc_defaults {
154 name: "framework-dokka-docs-default",
155 create_stubs: false,
156}
157
158droiddoc {
159 name: "doc-comment-check-docs",
160 defaults: ["framework-docs-default"],
161 srcs: [
162 ":framework-doc-stubs",
163 ],
164 args: framework_docs_only_args + " -referenceonly -parsecomments",
165 installable: false,
166}
167
168droiddoc {
169 name: "offline-sdk-docs",
170 defaults: ["framework-docs-default"],
171 srcs: [
172 ":framework-doc-stubs",
173 ],
174 hdf: [
175 "android.whichdoc offline",
176 ],
177 proofread_file: "offline-sdk-docs-proofrerad.txt",
178 args: framework_docs_only_args + " -offlinemode -title \"Android SDK\"",
179 static_doc_index_redirect: "docs/docs-preview-index.html",
180}
181
182droiddoc {
183 // Please sync with android-api-council@ before making any changes for the name property below.
184 // Since there's cron jobs that fetch offline-sdk-referenceonly-docs-docs.zip periodically.
185 // See b/116221385 for reference.
186 name: "offline-sdk-referenceonly-docs",
187 defaults: ["framework-docs-default"],
188 srcs: [
189 ":framework-doc-stubs",
190 ],
191 hdf: [
192 "android.whichdoc offline",
193 ],
194 proofread_file: "offline-sdk-referenceonly-docs-proofrerad.txt",
195 args: framework_docs_only_args + " -offlinemode -title \"Android SDK\" -referenceonly",
196 static_doc_index_redirect: "docs/docs-documentation-redirect.html",
197 static_doc_properties: "docs/source.properties",
198}
199
200droiddoc {
201 // Please sync with android-api-council@ before making any changes for the name property below.
202 // Since there's cron jobs that fetch offline-system-sdk-referenceonly-docs-docs.zip periodically.
203 // See b/116221385 for reference.
204 name: "offline-system-sdk-referenceonly-docs",
205 defaults: ["framework-docs-default"],
206 srcs: [
207 ":framework-doc-system-stubs",
208 ],
209 hdf: [
210 "android.whichdoc offline",
211 ],
212 proofread_file: "offline-system-sdk-referenceonly-docs-proofrerad.txt",
213 args: framework_docs_only_args + " -hide 101 -hide 104 -hide 108" +
214 " -offlinemode -title \"Android System SDK\" -referenceonly",
215 static_doc_index_redirect: "docs/docs-documentation-redirect.html",
216 static_doc_properties: "docs/source.properties",
217}
218
219droiddoc {
220 name: "online-sdk-docs",
221 defaults: ["framework-docs-default"],
222 srcs: [
223 ":framework-doc-stubs",
224 ],
225 hdf: [
226 "android.whichdoc online",
227 "android.hasSamples true",
228 ],
229 proofread_file: "online-sdk-docs-proofrerad.txt",
230 args: framework_docs_only_args +
231 " -toroot / -samplegroup Admin " +
232 " -samplegroup Background " +
233 " -samplegroup Connectivity " +
234 " -samplegroup Content " +
235 " -samplegroup Input " +
236 " -samplegroup Media " +
237 " -samplegroup Notification " +
238 " -samplegroup RenderScript " +
239 " -samplegroup Security " +
240 " -samplegroup Sensors " +
241 " -samplegroup System " +
242 " -samplegroup Testing " +
243 " -samplegroup UI " +
244 " -samplegroup Views " +
245 " -samplegroup Wearable -samplesdir development/samples/browseable ",
246}
247
248droiddoc {
249 name: "online-system-api-sdk-docs",
250 defaults: ["framework-docs-default"],
251 srcs: [
252 ":framework-doc-system-stubs",
253 ],
254 hdf: [
255 "android.whichdoc online",
256 "android.hasSamples true",
257 ],
258 proofread_file: "online-system-api-sdk-docs-proofrerad.txt",
259 args: framework_docs_only_args +
260 " -referenceonly " +
261 " -title \"Android SDK - Including system APIs.\" " +
262 " -hide 101 " +
263 " -hide 104 " +
264 " -hide 108 " +
265 " -toroot / -samplegroup Admin " +
266 " -samplegroup Background " +
267 " -samplegroup Connectivity " +
268 " -samplegroup Content " +
269 " -samplegroup Input " +
270 " -samplegroup Media " +
271 " -samplegroup Notification " +
272 " -samplegroup RenderScript " +
273 " -samplegroup Security " +
274 " -samplegroup Sensors " +
275 " -samplegroup System " +
276 " -samplegroup Testing " +
277 " -samplegroup UI " +
278 " -samplegroup Views " +
279 " -samplegroup Wearable -samplesdir development/samples/browseable ",
280 installable: false,
281}
282
283droiddoc {
284 name: "ds-docs-java",
285 defaults: ["framework-docs-default"],
286 srcs: [
287 ":framework-doc-stubs",
288 ],
289 hdf: [
290 "android.whichdoc online",
291 "android.hasSamples true",
292 ],
293 proofread_file: "ds-docs-proofrerad.txt",
294 args: framework_docs_only_args +
295 " -toroot / -yamlV2 -metalavaApiSince -samplegroup Admin " +
296 " -samplegroup Background " +
297 " -samplegroup Connectivity " +
298 " -samplegroup Content " +
299 " -samplegroup Input " +
300 " -samplegroup Media " +
301 " -samplegroup Notification " +
302 " -samplegroup RenderScript " +
303 " -samplegroup Security " +
304 " -samplegroup Sensors " +
305 " -samplegroup System " +
306 " -samplegroup Testing " +
307 " -samplegroup UI " +
308 " -samplegroup Views " +
309 " -samplegroup Wearable -devsite -samplesdir development/samples/browseable ",
310}
311
312droiddoc {
313 name: "ds-docs-kt",
314 defaults: ["framework-dokka-docs-default"],
315 srcs: [
316 ":framework-doc-stubs",
317 ],
318 args: "-noJdkLink -links https://kotlinlang.org/api/latest/jvm/stdlib/^external/dokka/package-list " +
319 "-noStdlibLink",
320 proofread_file: "ds-dokka-proofread.txt",
321 dokka_enabled: true,
322}
323
324java_genrule {
325 name: "ds-docs",
326 tools: [
327 "zip2zip",
328 "merge_zips",
329 ],
330 srcs: [
331 ":ds-docs-java{.docs.zip}",
332 ":ds-docs-kt{.docs.zip}",
333 ],
334 out: ["ds-docs.zip"],
335 dist: {
336 targets: ["docs"],
337 },
338 cmd: "$(location zip2zip) -i $(location :ds-docs-kt{.docs.zip}) -o $(genDir)/ds-docs-kt-moved.zip **/*:en/reference/kotlin && " +
339 "$(location merge_zips) $(out) $(location :ds-docs-java{.docs.zip}) $(genDir)/ds-docs-kt-moved.zip",
340}
341
342java_genrule {
343 name: "ds-docs-switched",
344 tools: [
345 "switcher4",
346 "soong_zip",
347 ],
348 srcs: [
349 ":ds-docs-java{.docs.zip}",
350 ":ds-docs-kt{.docs.zip}",
351 ],
352 out: ["ds-docs-switched.zip"],
353 dist: {
354 targets: ["docs"],
355 },
356 cmd: "unzip $(location :ds-docs-java{.docs.zip}) -d $(genDir) && " +
357 "unzip $(location :ds-docs-kt{.docs.zip}) -d $(genDir)/en/reference/kotlin && " +
358 "SWITCHER=$$(cd $$(dirname $(location switcher4)) && pwd)/$$(basename $(location switcher4)) && " +
359 "(cd $(genDir)/en/reference && $$SWITCHER --work platform) && " +
360 "$(location soong_zip) -o $(out) -C $(genDir) -D $(genDir)",
361}
362
363droiddoc {
364 name: "ds-static-docs",
365 defaults: ["framework-docs-default"],
366 srcs: [
367 ":framework-doc-stubs",
368 ],
369 hdf: [
370 "android.whichdoc online",
371 ],
372 proofread_file: "ds-static-docs-proofrerad.txt",
373 args: framework_docs_only_args +
374 " -staticonly " +
375 " -toroot / " +
376 " -devsite " +
377 " -ignoreJdLinks ",
378}
379
380droiddoc {
381 name: "ds-ref-navtree-docs",
382 defaults: ["framework-docs-default"],
383 srcs: [
384 ":framework-doc-stubs",
385 ],
386 hdf: [
387 "android.whichdoc online",
388 ],
389 proofread_file: "ds-ref-navtree-docs-proofrerad.txt",
390 args: framework_docs_only_args +
391 " -toroot / " +
392 " -atLinksNavtree " +
393 " -navtreeonly ",
394}
395
396droiddoc {
397 name: "online-sdk-dev-docs",
398 defaults: ["framework-docs-default"],
399 srcs: [
400 ":framework-doc-stubs",
401 ],
402 hdf: [
403 "android.whichdoc online",
404 "android.hasSamples true",
405 ],
406 proofread_file: "online-sdk-dev-docs-proofrerad.txt",
407 args: framework_docs_only_args +
408 " -toroot / -samplegroup Admin " +
409 " -samplegroup Background " +
410 " -samplegroup Connectivity " +
411 " -samplegroup Content " +
412 " -samplegroup Input " +
413 " -samplegroup Media " +
414 " -samplegroup Notification " +
415 " -samplegroup RenderScript " +
416 " -samplegroup Security " +
417 " -samplegroup Sensors " +
418 " -samplegroup System " +
419 " -samplegroup Testing " +
420 " -samplegroup UI " +
421 " -samplegroup Views " +
422 " -samplegroup Wearable -samplesdir development/samples/browseable ",
423}
424
425droiddoc {
426 name: "hidden-docs",
427 defaults: ["framework-docs-default"],
428 srcs: [
429 ":framework-doc-stubs",
430 ],
431 proofread_file: "hidden-docs-proofrerad.txt",
432 args: framework_docs_only_args +
433 " -referenceonly " +
434 " -title \"Android SDK - Including hidden APIs.\"",
435}
436