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
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        ":art-module-public-api-stubs-source",
69        ":conscrypt.module.public.api{.public.stubs.source}",
70        ":android_icu4j_public_api_files",
71        "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    ],
82    previous_api: ":android.api.public.latest",
83    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    ],
104    args: metalava_framework_docs_args + " --show-annotation android.annotation.SystemApi\\(client=android.annotation.SystemApi.Client.PRIVILEGED_APPS\\) ",
105    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",
125    libs: framework_docs_only_libs + [
126        "stub-annotations",
127        "unsupportedappusage",
128    ],
129    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    ],
180    compat_config: ":global-compat-config",
181    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
441