• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1// 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
58// These defaults enable doc-stub generation, api lint database generation and sdk value generation.
59stubs_defaults {
60    name: "android-non-updatable-doc-stubs-defaults",
61    defaults: ["android-non-updatable-stubs-defaults"],
62    srcs: [
63        // No longer part of the stubs, but are included in the docs.
64        ":android-test-base-sources",
65        ":android-test-mock-sources",
66        ":android-test-runner-sources",
67    ],
68    libs: framework_docs_only_libs,
69    create_doc_stubs: true,
70    write_sdk_values: true,
71}
72
73// Defaults module for doc-stubs targets that use module source code as input.
74stubs_defaults {
75    name: "framework-doc-stubs-sources-default",
76    defaults: ["android-non-updatable-doc-stubs-defaults"],
77    srcs: [
78        ":art.module.public.api{.public.stubs.source}",
79        ":conscrypt.module.public.api{.public.stubs.source}",
80        ":i18n.module.public.api{.public.stubs.source}",
81
82        ":framework-adservices-sources",
83        ":framework-appsearch-sources",
84        ":framework-connectivity-sources",
85        ":framework-bluetooth-sources",
86        ":framework-connectivity-tiramisu-updatable-sources",
87        ":framework-graphics-srcs",
88        ":framework-mediaprovider-sources",
89        ":framework-nearby-sources",
90        ":framework-ondevicepersonalization-sources",
91        ":framework-permission-sources",
92        ":framework-permission-s-sources",
93        ":framework-scheduling-sources",
94        ":framework-sdkextensions-sources",
95        ":framework-statsd-sources",
96        ":framework-sdksandbox-sources",
97        ":framework-tethering-srcs",
98        ":framework-uwb-updatable-sources",
99        ":framework-wifi-updatable-sources",
100        ":ike-srcs",
101        ":updatable-media-srcs",
102    ],
103}
104
105droidstubs {
106    name: "android-non-updatable-doc-stubs",
107    defaults: [
108        "android-non-updatable-doc-stubs-defaults",
109        "module-classpath-stubs-defaults",
110    ],
111    args: metalava_framework_docs_args,
112}
113
114droidstubs {
115    name: "android-non-updatable-doc-stubs-system",
116    defaults: [
117        "android-non-updatable-doc-stubs-defaults",
118        "module-classpath-stubs-defaults",
119    ],
120    args: metalava_framework_docs_args +
121        " --show-annotation android.annotation.SystemApi\\(client=android.annotation.SystemApi.Client.PRIVILEGED_APPS\\) ",
122}
123
124droidstubs {
125    name: "android-non-updatable-doc-stubs-module-lib",
126    defaults: [
127        "android-non-updatable-doc-stubs-defaults",
128        "module-classpath-stubs-defaults",
129    ],
130    args: metalava_framework_docs_args +
131        " --show-annotation android.annotation.SystemApi\\(client=android.annotation.SystemApi.Client.PRIVILEGED_APPS\\) " +
132        " --show-annotation android.annotation.SystemApi\\(client=android.annotation.SystemApi.Client.MODULE_LIBRARIES\\) ",
133    generate_stubs: false, // We're only using this module for the annotations.zip output, disable doc-stubs.
134    write_sdk_values: false,
135}
136
137droidstubs {
138    name: "android-non-updatable-doc-stubs-system-server",
139    defaults: [
140        "android-non-updatable-doc-stubs-defaults",
141        "module-classpath-stubs-defaults",
142    ],
143    args: metalava_framework_docs_args +
144        " --show-annotation android.annotation.SystemApi\\(client=android.annotation.SystemApi.Client.PRIVILEGED_APPS\\) " +
145        " --show-annotation android.annotation.SystemApi\\(client=android.annotation.SystemApi.Client.MODULE_LIBRARIES\\) " +
146        " --show-annotation android.annotation.SystemApi\\(client=android.annotation.SystemApi.Client.SYSTEM_SERVER\\) ",
147    generate_stubs: false, // We're only using this module for the annotations.zip output, disable doc-stubs.
148    write_sdk_values: false,
149}
150
151droidstubs {
152    name: "framework-doc-stubs",
153    defaults: ["android-non-updatable-doc-stubs-defaults"],
154    srcs: [":all-modules-public-stubs-source"],
155    args: metalava_framework_docs_args,
156    api_levels_module: "api_versions_public",
157    aidl: {
158        include_dirs: [
159            "packages/modules/Connectivity/framework/aidl-export",
160            "packages/modules/Media/apex/aidl/stable",
161        ],
162    },
163    extensions_info_file: ":sdk-extensions-info",
164}
165
166droidstubs {
167    name: "framework-doc-system-stubs",
168    defaults: ["framework-doc-stubs-sources-default"],
169    args: metalava_framework_docs_args +
170        " --show-annotation android.annotation.SystemApi\\(client=android.annotation.SystemApi.Client.PRIVILEGED_APPS\\) ",
171    api_levels_annotations_enabled: true,
172    api_levels_annotations_dirs: [
173        "sdk-dir",
174        "api-versions-jars-dir",
175    ],
176    api_levels_sdk_type: "system",
177    extensions_info_file: ":sdk-extensions-info",
178}
179
180/////////////////////////////////////////////////////////////////////
181// API docs are created from the generated stub source files
182// using droiddoc
183/////////////////////////////////////////////////////////////////////
184
185framework_docs_only_args = " -android -manifest $(location :frameworks-base-core-AndroidManifest.xml) " +
186    "-metalavaApiSince " +
187    "-werror -lerror -hide 111 -hide 113 -hide 125 -hide 126 -hide 127 -hide 128 " +
188    "-overview $(location :frameworks-base-java-overview) " +
189    // Federate Support Library references against local API file.
190    "-federate SupportLib https://developer.android.com " +
191    "-federationapi SupportLib $(location :current-support-api) " +
192    // Federate Support Library references against local API file.
193    "-federate AndroidX https://developer.android.com " +
194    "-federationapi AndroidX $(location :current-androidx-api) "
195
196doc_defaults {
197    name: "framework-docs-default",
198    libs: framework_docs_only_libs + [
199        "stub-annotations",
200        "unsupportedappusage",
201    ],
202    html_dirs: [
203        "docs/html",
204    ],
205    knowntags: [
206        "docs/knowntags.txt",
207        ":art.module.public.api{.doctags}",
208    ],
209    custom_template: "droiddoc-templates-sdk",
210    resourcesdir: "docs/html/reference/images/",
211    resourcesoutdir: "reference/android/images/",
212    hdf: [
213        "dac true",
214        "sdk.codename O",
215        "sdk.preview.version 1",
216        "sdk.version 7.0",
217        "sdk.rel.id 1",
218        "sdk.preview 0",
219    ],
220    arg_files: [
221        ":frameworks-base-core-AndroidManifest.xml",
222        ":frameworks-base-java-overview",
223        ":current-support-api",
224        ":current-androidx-api",
225    ],
226    // TODO(b/169090544): remove below aidl includes.
227    aidl: {
228        include_dirs: [
229            "frameworks/av/aidl",
230            "frameworks/base/media/aidl",
231            "frameworks/native/libs/permission/aidl",
232        ],
233    },
234}
235
236doc_defaults {
237    name: "framework-dokka-docs-default",
238}
239
240droiddoc {
241    name: "doc-comment-check-docs",
242    defaults: ["framework-docs-default"],
243    srcs: [
244        ":framework-doc-stubs",
245    ],
246    args: framework_docs_only_args + " -referenceonly -parsecomments",
247    installable: false,
248}
249
250droiddoc {
251    name: "offline-sdk-docs",
252    defaults: ["framework-docs-default"],
253    srcs: [
254        ":framework-doc-stubs",
255    ],
256    hdf: [
257        "android.whichdoc offline",
258    ],
259    compat_config: ":global-compat-config",
260    proofread_file: "offline-sdk-docs-proofread.txt",
261    args: framework_docs_only_args + " -offlinemode -title \"Android SDK\"",
262    static_doc_index_redirect: "docs/docs-preview-index.html",
263}
264
265droiddoc {
266    // Please sync with android-api-council@ before making any changes for the name property below.
267    // Since there's cron jobs that fetch offline-sdk-referenceonly-docs-docs.zip periodically.
268    // See b/116221385 for reference.
269    name: "offline-sdk-referenceonly-docs",
270    defaults: ["framework-docs-default"],
271    srcs: [
272        ":framework-doc-stubs",
273    ],
274    hdf: [
275        "android.whichdoc offline",
276    ],
277    proofread_file: "offline-sdk-referenceonly-docs-proofread.txt",
278    args: framework_docs_only_args + " -offlinemode -title \"Android SDK\" -referenceonly",
279    static_doc_index_redirect: "docs/docs-documentation-redirect.html",
280    static_doc_properties: "docs/source.properties",
281}
282
283droiddoc {
284    // Please sync with android-api-council@ before making any changes for the name property below.
285    // Since there's cron jobs that fetch offline-system-sdk-referenceonly-docs-docs.zip periodically.
286    // See b/116221385 for reference.
287    name: "offline-system-sdk-referenceonly-docs",
288    defaults: ["framework-docs-default"],
289    srcs: [
290        ":framework-doc-system-stubs",
291    ],
292    hdf: [
293        "android.whichdoc offline",
294    ],
295    proofread_file: "offline-system-sdk-referenceonly-docs-proofread.txt",
296    args: framework_docs_only_args + " -hide 101 -hide 104 -hide 108" +
297    " -offlinemode -title \"Android System SDK\" -referenceonly",
298    static_doc_index_redirect: "docs/docs-documentation-redirect.html",
299    static_doc_properties: "docs/source.properties",
300}
301
302droiddoc {
303    name: "online-sdk-docs",
304    defaults: ["framework-docs-default"],
305    srcs: [
306        ":framework-doc-stubs",
307    ],
308    hdf: [
309        "android.whichdoc online",
310        "android.hasSamples true",
311    ],
312    proofread_file: "online-sdk-docs-proofread.txt",
313    args: framework_docs_only_args +
314        " -toroot / -samplegroup Admin " +
315        " -samplegroup Background " +
316        " -samplegroup Connectivity " +
317        " -samplegroup Content " +
318        " -samplegroup Input " +
319        " -samplegroup Media " +
320        " -samplegroup Notification " +
321        " -samplegroup RenderScript " +
322        " -samplegroup Security " +
323        " -samplegroup Sensors " +
324        " -samplegroup System " +
325        " -samplegroup Testing " +
326        " -samplegroup UI " +
327        " -samplegroup Views " +
328        " -samplegroup Wearable -samplesdir development/samples/browseable ",
329}
330
331droiddoc {
332    name: "online-system-api-sdk-docs",
333    defaults: ["framework-docs-default"],
334    srcs: [
335        ":framework-doc-system-stubs",
336    ],
337    hdf: [
338        "android.whichdoc online",
339        "android.hasSamples true",
340    ],
341    proofread_file: "online-system-api-sdk-docs-proofread.txt",
342    args: framework_docs_only_args +
343        " -referenceonly " +
344        " -title \"Android SDK - Including system APIs.\" " +
345        " -hide 101 " +
346        " -hide 104 " +
347        " -hide 108 " +
348        " -toroot / -samplegroup Admin " +
349        " -samplegroup Background " +
350        " -samplegroup Connectivity " +
351        " -samplegroup Content " +
352        " -samplegroup Input " +
353        " -samplegroup Media " +
354        " -samplegroup Notification " +
355        " -samplegroup RenderScript " +
356        " -samplegroup Security " +
357        " -samplegroup Sensors " +
358        " -samplegroup System " +
359        " -samplegroup Testing " +
360        " -samplegroup UI " +
361        " -samplegroup Views " +
362        " -samplegroup Wearable -samplesdir development/samples/browseable ",
363    installable: false,
364}
365
366droiddoc {
367    name: "ds-docs-java",
368    defaults: ["framework-docs-default"],
369    srcs: [
370        ":framework-doc-stubs",
371    ],
372    hdf: [
373        "android.whichdoc online",
374        "android.hasSamples true",
375    ],
376    proofread_file: "ds-docs-proofread.txt",
377    args: framework_docs_only_args +
378        " -toroot / -yamlV2 -samplegroup Admin " +
379        " -samplegroup Background " +
380        " -samplegroup Connectivity " +
381        " -samplegroup Content " +
382        " -samplegroup Input " +
383        " -samplegroup Media " +
384        " -samplegroup Notification " +
385        " -samplegroup RenderScript " +
386        " -samplegroup Security " +
387        " -samplegroup Sensors " +
388        " -samplegroup System " +
389        " -samplegroup Testing " +
390        " -samplegroup UI " +
391        " -samplegroup Views " +
392        " -samplegroup Wearable -devsite -samplesdir development/samples/browseable ",
393}
394
395droiddoc {
396    name: "ds-docs-kt",
397    defaults: ["framework-dokka-docs-default"],
398    srcs: [
399        ":framework-doc-stubs",
400    ],
401    args: "-noJdkLink -links https://kotlinlang.org/api/latest/jvm/stdlib/^external/dokka/package-list " +
402        "-noStdlibLink",
403    proofread_file: "ds-dokka-proofread.txt",
404    dokka_enabled: true,
405}
406
407java_genrule {
408    name: "ds-docs",
409    tools: [
410        "zip2zip",
411        "merge_zips",
412    ],
413    srcs: [
414        ":ds-docs-java{.docs.zip}",
415        ":ds-docs-kt{.docs.zip}",
416    ],
417    out: ["ds-docs.zip"],
418    dist: {
419        targets: ["docs"],
420    },
421    cmd: "$(location zip2zip) -i $(location :ds-docs-kt{.docs.zip}) -o $(genDir)/ds-docs-kt-moved.zip **/*:en/reference/kotlin && " +
422        "$(location merge_zips) $(out) $(location :ds-docs-java{.docs.zip}) $(genDir)/ds-docs-kt-moved.zip",
423}
424
425java_genrule {
426    name: "ds-docs-switched",
427    tools: [
428        "switcher4",
429        "soong_zip",
430    ],
431    srcs: [
432        ":ds-docs-java{.docs.zip}",
433        ":ds-docs-kt{.docs.zip}",
434    ],
435    out: ["ds-docs-switched.zip"],
436    dist: {
437        targets: ["docs"],
438    },
439    cmd: "unzip -q $(location :ds-docs-java{.docs.zip}) -d $(genDir) && " +
440        "unzip -q $(location :ds-docs-kt{.docs.zip}) -d $(genDir)/en/reference/kotlin && " +
441        "SWITCHER=$$(cd $$(dirname $(location switcher4)) && pwd)/$$(basename $(location switcher4)) && " +
442        "(cd $(genDir)/en/reference && $$SWITCHER --work platform) > /dev/null && " +
443        "$(location soong_zip) -o $(out) -C $(genDir) -D $(genDir)",
444}
445
446droiddoc {
447    name: "ds-static-docs",
448    defaults: ["framework-docs-default"],
449    srcs: [
450        ":framework-doc-stubs",
451    ],
452    hdf: [
453        "android.whichdoc online",
454    ],
455    args: framework_docs_only_args +
456        " -staticonly " +
457        " -toroot / " +
458        " -devsite " +
459        " -ignoreJdLinks ",
460}
461
462droiddoc {
463    name: "ds-ref-navtree-docs",
464    defaults: ["framework-docs-default"],
465    srcs: [
466        ":framework-doc-stubs",
467    ],
468    hdf: [
469        "android.whichdoc online",
470    ],
471    args: framework_docs_only_args +
472        " -toroot / " +
473        " -atLinksNavtree " +
474        " -navtreeonly ",
475}
476
477droiddoc {
478    name: "online-sdk-dev-docs",
479    defaults: ["framework-docs-default"],
480    srcs: [
481        ":framework-doc-stubs",
482    ],
483    hdf: [
484        "android.whichdoc online",
485        "android.hasSamples true",
486    ],
487    proofread_file: "online-sdk-dev-docs-proofread.txt",
488    args: framework_docs_only_args +
489        " -toroot / -samplegroup Admin " +
490        " -samplegroup Background " +
491        " -samplegroup Connectivity " +
492        " -samplegroup Content " +
493        " -samplegroup Input " +
494        " -samplegroup Media " +
495        " -samplegroup Notification " +
496        " -samplegroup RenderScript " +
497        " -samplegroup Security " +
498        " -samplegroup Sensors " +
499        " -samplegroup System " +
500        " -samplegroup Testing " +
501        " -samplegroup UI " +
502        " -samplegroup Views " +
503        " -samplegroup Wearable -samplesdir development/samples/browseable ",
504}
505
506droiddoc {
507    name: "hidden-docs",
508    defaults: ["framework-docs-default"],
509    srcs: [
510        ":framework-doc-stubs",
511    ],
512    proofread_file: "hidden-docs-proofread.txt",
513    args: framework_docs_only_args +
514        " -referenceonly " +
515        " -title \"Android SDK - Including hidden APIs.\"",
516}
517