Jiyong Park | 7fb4b18 | 2019-12-20 14:35:43 +0900 | [diff] [blame] | 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 | ":core-current-stubs-source", |
| 69 | ":core_public_api_files", |
| 70 | "test-mock/src/**/*.java", |
| 71 | "test-runner/src/**/*.java", |
| 72 | ], |
| 73 | libs: framework_docs_only_libs, |
| 74 | create_doc_stubs: true, |
| 75 | annotations_enabled: true, |
| 76 | api_levels_annotations_enabled: true, |
| 77 | api_levels_annotations_dirs: [ |
| 78 | "sdk-dir", |
| 79 | "api-versions-jars-dir", |
| 80 | ], |
| 81 | previous_api: ":last-released-public-api", |
| 82 | merge_annotations_dirs: [ |
| 83 | "metalava-manual", |
| 84 | ], |
| 85 | } |
| 86 | |
| 87 | droidstubs { |
| 88 | name: "framework-doc-stubs", |
| 89 | defaults: ["framework-doc-stubs-default"], |
| 90 | arg_files: [ |
| 91 | "core/res/AndroidManifest.xml", |
| 92 | ], |
| 93 | args: metalava_framework_docs_args, |
| 94 | write_sdk_values: true, |
| 95 | } |
| 96 | |
| 97 | droidstubs { |
| 98 | name: "framework-doc-system-stubs", |
| 99 | defaults: ["framework-doc-stubs-default"], |
| 100 | arg_files: [ |
| 101 | "core/res/AndroidManifest.xml", |
| 102 | ], |
| 103 | args: metalava_framework_docs_args + " --show-annotation android.annotation.SystemApi\\(client=android.annotation.SystemApi.Client.PRIVILEGED_APPS,process=android.annotation.SystemApi.Process.ALL\\) ", |
| 104 | write_sdk_values: true, |
| 105 | } |
| 106 | |
| 107 | ///////////////////////////////////////////////////////////////////// |
| 108 | // API docs are created from the generated stub source files |
| 109 | // using droiddoc |
| 110 | ///////////////////////////////////////////////////////////////////// |
| 111 | |
| 112 | framework_docs_only_args = " -android -manifest $(location core/res/AndroidManifest.xml) " + |
| 113 | "-werror -lerror -hide 111 -hide 113 -hide 125 -hide 126 -hide 127 -hide 128 " + |
| 114 | "-overview $(location core/java/overview.html) " + |
| 115 | // Federate Support Library references against local API file. |
| 116 | "-federate SupportLib https://developer.android.com " + |
| 117 | "-federationapi SupportLib $(location :current-support-api) " + |
| 118 | // Federate Support Library references against local API file. |
| 119 | "-federate AndroidX https://developer.android.com " + |
| 120 | "-federationapi AndroidX $(location :current-androidx-api) " |
| 121 | |
| 122 | doc_defaults { |
| 123 | name: "framework-docs-default", |
Artur Satayev | ffd7f95 | 2020-01-13 16:16:27 +0000 | [diff] [blame] | 124 | libs: framework_docs_only_libs + [ |
| 125 | "stub-annotations", |
| 126 | "unsupportedappusage", |
| 127 | ], |
Jiyong Park | 7fb4b18 | 2019-12-20 14:35:43 +0900 | [diff] [blame] | 128 | html_dirs: [ |
| 129 | "docs/html", |
| 130 | ], |
| 131 | knowntags: [ |
| 132 | "docs/knowntags.txt", |
| 133 | ":known-oj-tags", |
| 134 | ], |
| 135 | custom_template: "droiddoc-templates-sdk", |
| 136 | resourcesdir: "docs/html/reference/images/", |
| 137 | resourcesoutdir: "reference/android/images/", |
| 138 | hdf: [ |
| 139 | "dac true", |
| 140 | "sdk.codename O", |
| 141 | "sdk.preview.version 1", |
| 142 | "sdk.version 7.0", |
| 143 | "sdk.rel.id 1", |
| 144 | "sdk.preview 0", |
| 145 | ], |
| 146 | arg_files: [ |
| 147 | "core/res/AndroidManifest.xml", |
| 148 | "core/java/overview.html", |
| 149 | ":current-support-api", |
| 150 | ":current-androidx-api", |
| 151 | ], |
| 152 | create_stubs: false, |
| 153 | } |
| 154 | |
| 155 | doc_defaults { |
| 156 | name: "framework-dokka-docs-default", |
| 157 | create_stubs: false, |
| 158 | } |
| 159 | |
| 160 | droiddoc { |
| 161 | name: "doc-comment-check-docs", |
| 162 | defaults: ["framework-docs-default"], |
| 163 | srcs: [ |
| 164 | ":framework-doc-stubs", |
| 165 | ], |
| 166 | args: framework_docs_only_args + " -referenceonly -parsecomments", |
| 167 | installable: false, |
| 168 | } |
| 169 | |
| 170 | droiddoc { |
| 171 | name: "offline-sdk-docs", |
| 172 | defaults: ["framework-docs-default"], |
| 173 | srcs: [ |
| 174 | ":framework-doc-stubs", |
| 175 | ], |
| 176 | hdf: [ |
| 177 | "android.whichdoc offline", |
| 178 | ], |
atrost | b1ee27b3 | 2020-02-03 11:03:16 +0000 | [diff] [blame] | 179 | compat_config: ":global-compat-config", |
Jiyong Park | 7fb4b18 | 2019-12-20 14:35:43 +0900 | [diff] [blame] | 180 | proofread_file: "offline-sdk-docs-proofrerad.txt", |
| 181 | args: framework_docs_only_args + " -offlinemode -title \"Android SDK\"", |
| 182 | static_doc_index_redirect: "docs/docs-preview-index.html", |
| 183 | } |
| 184 | |
| 185 | droiddoc { |
| 186 | // Please sync with android-api-council@ before making any changes for the name property below. |
| 187 | // Since there's cron jobs that fetch offline-sdk-referenceonly-docs-docs.zip periodically. |
| 188 | // See b/116221385 for reference. |
| 189 | name: "offline-sdk-referenceonly-docs", |
| 190 | defaults: ["framework-docs-default"], |
| 191 | srcs: [ |
| 192 | ":framework-doc-stubs", |
| 193 | ], |
| 194 | hdf: [ |
| 195 | "android.whichdoc offline", |
| 196 | ], |
| 197 | proofread_file: "offline-sdk-referenceonly-docs-proofrerad.txt", |
| 198 | args: framework_docs_only_args + " -offlinemode -title \"Android SDK\" -referenceonly", |
| 199 | static_doc_index_redirect: "docs/docs-documentation-redirect.html", |
| 200 | static_doc_properties: "docs/source.properties", |
| 201 | } |
| 202 | |
| 203 | droiddoc { |
| 204 | // Please sync with android-api-council@ before making any changes for the name property below. |
| 205 | // Since there's cron jobs that fetch offline-system-sdk-referenceonly-docs-docs.zip periodically. |
| 206 | // See b/116221385 for reference. |
| 207 | name: "offline-system-sdk-referenceonly-docs", |
| 208 | defaults: ["framework-docs-default"], |
| 209 | srcs: [ |
| 210 | ":framework-doc-system-stubs", |
| 211 | ], |
| 212 | hdf: [ |
| 213 | "android.whichdoc offline", |
| 214 | ], |
| 215 | proofread_file: "offline-system-sdk-referenceonly-docs-proofrerad.txt", |
| 216 | args: framework_docs_only_args + " -hide 101 -hide 104 -hide 108" + |
| 217 | " -offlinemode -title \"Android System SDK\" -referenceonly", |
| 218 | static_doc_index_redirect: "docs/docs-documentation-redirect.html", |
| 219 | static_doc_properties: "docs/source.properties", |
| 220 | } |
| 221 | |
| 222 | droiddoc { |
| 223 | name: "online-sdk-docs", |
| 224 | defaults: ["framework-docs-default"], |
| 225 | srcs: [ |
| 226 | ":framework-doc-stubs", |
| 227 | ], |
| 228 | hdf: [ |
| 229 | "android.whichdoc online", |
| 230 | "android.hasSamples true", |
| 231 | ], |
| 232 | proofread_file: "online-sdk-docs-proofrerad.txt", |
| 233 | args: framework_docs_only_args + |
| 234 | " -toroot / -samplegroup Admin " + |
| 235 | " -samplegroup Background " + |
| 236 | " -samplegroup Connectivity " + |
| 237 | " -samplegroup Content " + |
| 238 | " -samplegroup Input " + |
| 239 | " -samplegroup Media " + |
| 240 | " -samplegroup Notification " + |
| 241 | " -samplegroup RenderScript " + |
| 242 | " -samplegroup Security " + |
| 243 | " -samplegroup Sensors " + |
| 244 | " -samplegroup System " + |
| 245 | " -samplegroup Testing " + |
| 246 | " -samplegroup UI " + |
| 247 | " -samplegroup Views " + |
| 248 | " -samplegroup Wearable -samplesdir development/samples/browseable ", |
| 249 | } |
| 250 | |
| 251 | droiddoc { |
| 252 | name: "online-system-api-sdk-docs", |
| 253 | defaults: ["framework-docs-default"], |
| 254 | srcs: [ |
| 255 | ":framework-doc-system-stubs", |
| 256 | ], |
| 257 | hdf: [ |
| 258 | "android.whichdoc online", |
| 259 | "android.hasSamples true", |
| 260 | ], |
| 261 | proofread_file: "online-system-api-sdk-docs-proofrerad.txt", |
| 262 | args: framework_docs_only_args + |
| 263 | " -referenceonly " + |
| 264 | " -title \"Android SDK - Including system APIs.\" " + |
| 265 | " -hide 101 " + |
| 266 | " -hide 104 " + |
| 267 | " -hide 108 " + |
| 268 | " -toroot / -samplegroup Admin " + |
| 269 | " -samplegroup Background " + |
| 270 | " -samplegroup Connectivity " + |
| 271 | " -samplegroup Content " + |
| 272 | " -samplegroup Input " + |
| 273 | " -samplegroup Media " + |
| 274 | " -samplegroup Notification " + |
| 275 | " -samplegroup RenderScript " + |
| 276 | " -samplegroup Security " + |
| 277 | " -samplegroup Sensors " + |
| 278 | " -samplegroup System " + |
| 279 | " -samplegroup Testing " + |
| 280 | " -samplegroup UI " + |
| 281 | " -samplegroup Views " + |
| 282 | " -samplegroup Wearable -samplesdir development/samples/browseable ", |
| 283 | installable: false, |
| 284 | } |
| 285 | |
| 286 | droiddoc { |
| 287 | name: "ds-docs-java", |
| 288 | defaults: ["framework-docs-default"], |
| 289 | srcs: [ |
| 290 | ":framework-doc-stubs", |
| 291 | ], |
| 292 | hdf: [ |
| 293 | "android.whichdoc online", |
| 294 | "android.hasSamples true", |
| 295 | ], |
| 296 | proofread_file: "ds-docs-proofrerad.txt", |
| 297 | args: framework_docs_only_args + |
| 298 | " -toroot / -yamlV2 -metalavaApiSince -samplegroup Admin " + |
| 299 | " -samplegroup Background " + |
| 300 | " -samplegroup Connectivity " + |
| 301 | " -samplegroup Content " + |
| 302 | " -samplegroup Input " + |
| 303 | " -samplegroup Media " + |
| 304 | " -samplegroup Notification " + |
| 305 | " -samplegroup RenderScript " + |
| 306 | " -samplegroup Security " + |
| 307 | " -samplegroup Sensors " + |
| 308 | " -samplegroup System " + |
| 309 | " -samplegroup Testing " + |
| 310 | " -samplegroup UI " + |
| 311 | " -samplegroup Views " + |
| 312 | " -samplegroup Wearable -devsite -samplesdir development/samples/browseable ", |
| 313 | } |
| 314 | |
| 315 | droiddoc { |
| 316 | name: "ds-docs-kt", |
| 317 | defaults: ["framework-dokka-docs-default"], |
| 318 | srcs: [ |
| 319 | ":framework-doc-stubs", |
| 320 | ], |
| 321 | args: "-noJdkLink -links https://kotlinlang.org/api/latest/jvm/stdlib/^external/dokka/package-list " + |
| 322 | "-noStdlibLink", |
| 323 | proofread_file: "ds-dokka-proofread.txt", |
| 324 | dokka_enabled: true, |
| 325 | } |
| 326 | |
| 327 | java_genrule { |
| 328 | name: "ds-docs", |
| 329 | tools: [ |
| 330 | "zip2zip", |
| 331 | "merge_zips", |
| 332 | ], |
| 333 | srcs: [ |
| 334 | ":ds-docs-java{.docs.zip}", |
| 335 | ":ds-docs-kt{.docs.zip}", |
| 336 | ], |
| 337 | out: ["ds-docs.zip"], |
| 338 | dist: { |
| 339 | targets: ["docs"], |
| 340 | }, |
| 341 | cmd: "$(location zip2zip) -i $(location :ds-docs-kt{.docs.zip}) -o $(genDir)/ds-docs-kt-moved.zip **/*:en/reference/kotlin && " + |
| 342 | "$(location merge_zips) $(out) $(location :ds-docs-java{.docs.zip}) $(genDir)/ds-docs-kt-moved.zip", |
| 343 | } |
| 344 | |
| 345 | java_genrule { |
| 346 | name: "ds-docs-switched", |
| 347 | tools: [ |
| 348 | "switcher4", |
| 349 | "soong_zip", |
| 350 | ], |
| 351 | srcs: [ |
| 352 | ":ds-docs-java{.docs.zip}", |
| 353 | ":ds-docs-kt{.docs.zip}", |
| 354 | ], |
| 355 | out: ["ds-docs-switched.zip"], |
| 356 | dist: { |
| 357 | targets: ["docs"], |
| 358 | }, |
| 359 | cmd: "unzip $(location :ds-docs-java{.docs.zip}) -d $(genDir) && " + |
| 360 | "unzip $(location :ds-docs-kt{.docs.zip}) -d $(genDir)/en/reference/kotlin && " + |
| 361 | "SWITCHER=$$(cd $$(dirname $(location switcher4)) && pwd)/$$(basename $(location switcher4)) && " + |
| 362 | "(cd $(genDir)/en/reference && $$SWITCHER --work platform) && " + |
| 363 | "$(location soong_zip) -o $(out) -C $(genDir) -D $(genDir)", |
| 364 | } |
| 365 | |
| 366 | droiddoc { |
| 367 | name: "ds-static-docs", |
| 368 | defaults: ["framework-docs-default"], |
| 369 | srcs: [ |
| 370 | ":framework-doc-stubs", |
| 371 | ], |
| 372 | hdf: [ |
| 373 | "android.whichdoc online", |
| 374 | ], |
| 375 | proofread_file: "ds-static-docs-proofrerad.txt", |
| 376 | args: framework_docs_only_args + |
| 377 | " -staticonly " + |
| 378 | " -toroot / " + |
| 379 | " -devsite " + |
| 380 | " -ignoreJdLinks ", |
| 381 | } |
| 382 | |
| 383 | droiddoc { |
| 384 | name: "ds-ref-navtree-docs", |
| 385 | defaults: ["framework-docs-default"], |
| 386 | srcs: [ |
| 387 | ":framework-doc-stubs", |
| 388 | ], |
| 389 | hdf: [ |
| 390 | "android.whichdoc online", |
| 391 | ], |
| 392 | proofread_file: "ds-ref-navtree-docs-proofrerad.txt", |
| 393 | args: framework_docs_only_args + |
| 394 | " -toroot / " + |
| 395 | " -atLinksNavtree " + |
| 396 | " -navtreeonly ", |
| 397 | } |
| 398 | |
| 399 | droiddoc { |
| 400 | name: "online-sdk-dev-docs", |
| 401 | defaults: ["framework-docs-default"], |
| 402 | srcs: [ |
| 403 | ":framework-doc-stubs", |
| 404 | ], |
| 405 | hdf: [ |
| 406 | "android.whichdoc online", |
| 407 | "android.hasSamples true", |
| 408 | ], |
| 409 | proofread_file: "online-sdk-dev-docs-proofrerad.txt", |
| 410 | args: framework_docs_only_args + |
| 411 | " -toroot / -samplegroup Admin " + |
| 412 | " -samplegroup Background " + |
| 413 | " -samplegroup Connectivity " + |
| 414 | " -samplegroup Content " + |
| 415 | " -samplegroup Input " + |
| 416 | " -samplegroup Media " + |
| 417 | " -samplegroup Notification " + |
| 418 | " -samplegroup RenderScript " + |
| 419 | " -samplegroup Security " + |
| 420 | " -samplegroup Sensors " + |
| 421 | " -samplegroup System " + |
| 422 | " -samplegroup Testing " + |
| 423 | " -samplegroup UI " + |
| 424 | " -samplegroup Views " + |
| 425 | " -samplegroup Wearable -samplesdir development/samples/browseable ", |
| 426 | } |
| 427 | |
| 428 | droiddoc { |
| 429 | name: "hidden-docs", |
| 430 | defaults: ["framework-docs-default"], |
| 431 | srcs: [ |
| 432 | ":framework-doc-stubs", |
| 433 | ], |
| 434 | proofread_file: "hidden-docs-proofrerad.txt", |
| 435 | args: framework_docs_only_args + |
| 436 | " -referenceonly " + |
| 437 | " -title \"Android SDK - Including hidden APIs.\"", |
| 438 | } |
| 439 | |