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