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