ApiDocs.bp

   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
  27 framework_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 stubs_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
  88 droidstubs {
  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
  98 droidstubs {
  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
 113 framework_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
 123 doc_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
 156 doc_defaults {
 157     name: "framework-dokka-docs-default",
 158     create_stubs: false,
 159 }
 160
 161 droiddoc {
 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
 171 droiddoc {
 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
 186 droiddoc {
 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
 204 droiddoc {
 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
 223 droiddoc {
 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
 252 droiddoc {
 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
 287 droiddoc {
 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
 316 droiddoc {
 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
 328 java_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
 346 java_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
 367 droiddoc {
 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
 384 droiddoc {
 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
 400 droiddoc {
 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
 429 droiddoc {
 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