From 19fcec6c634c28c1a842d7164d94a46b3ef59942 Mon Sep 17 00:00:00 2001 From: Anton Hansson Date: Tue, 2 May 2023 08:57:12 +0000 Subject: Move ApiDocs.bp and StubLibraries.bp to api dir Make a symlink from api/docs -> docs, since many places are hardcoding the path fw/base/docs. Bug: 271563074 Test: presubmit Change-Id: I354f3cb62535f34d8819d158e53aa46ff26dc18a --- api/ApiDocs.bp | 516 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 516 insertions(+) create mode 100644 api/ApiDocs.bp (limited to 'api/ApiDocs.bp') diff --git a/api/ApiDocs.bp b/api/ApiDocs.bp new file mode 100644 index 000000000000..fbcaa52f9bb4 --- /dev/null +++ b/api/ApiDocs.bp @@ -0,0 +1,516 @@ +// Copyright (C) 2019 The Android Open Source Project +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +// How API docs are generated: +// +// raw source files --(metalava)--> stub source files --(doclava)--> API doc +// +// The metalava conversion is done by droidstub modules framework-doc-*-stubs. +// The API doc generation is done by the various droiddoc modules each of which +// is for different format. + +///////////////////////////////////////////////////////////////////// +// stub source files are generated using metalava +///////////////////////////////////////////////////////////////////// + +framework_docs_only_libs = [ + "voip-common", + "android.test.mock", + "android-support-annotations", + "android-support-compat", + "android-support-core-ui", + "android-support-core-utils", + "android-support-design", + "android-support-dynamic-animation", + "android-support-exifinterface", + "android-support-fragment", + "android-support-media-compat", + "android-support-percent", + "android-support-transition", + "android-support-v7-cardview", + "android-support-v7-gridlayout", + "android-support-v7-mediarouter", + "android-support-v7-palette", + "android-support-v7-preference", + "android-support-v13", + "android-support-v14-preference", + "android-support-v17-leanback", + "android-support-vectordrawable", + "android-support-animatedvectordrawable", + "android-support-v7-appcompat", + "android-support-v7-recyclerview", + "android-support-v8-renderscript", + "android-support-multidex", + "android-support-multidex-instrumentation", +] + +// These defaults enable doc-stub generation, api lint database generation and sdk value generation. +stubs_defaults { + name: "android-non-updatable-doc-stubs-defaults", + defaults: ["android-non-updatable-stubs-defaults"], + srcs: [ + // No longer part of the stubs, but are included in the docs. + ":android-test-base-sources", + ":android-test-mock-sources", + ":android-test-runner-sources", + ], + libs: framework_docs_only_libs, + create_doc_stubs: true, + write_sdk_values: true, +} + +// Defaults module for doc-stubs targets that use module source code as input. +stubs_defaults { + name: "framework-doc-stubs-sources-default", + defaults: ["android-non-updatable-doc-stubs-defaults"], + srcs: [ + ":art.module.public.api{.public.stubs.source}", + ":conscrypt.module.public.api{.public.stubs.source}", + ":i18n.module.public.api{.public.stubs.source}", + + ":framework-adservices-sources", + ":framework-appsearch-sources", + ":framework-connectivity-sources", + ":framework-bluetooth-sources", + ":framework-connectivity-tiramisu-updatable-sources", + ":framework-graphics-srcs", + ":framework-mediaprovider-sources", + ":framework-nearby-sources", + ":framework-ondevicepersonalization-sources", + ":framework-permission-sources", + ":framework-permission-s-sources", + ":framework-scheduling-sources", + ":framework-sdkextensions-sources", + ":framework-statsd-sources", + ":framework-sdksandbox-sources", + ":framework-tethering-srcs", + ":framework-uwb-updatable-sources", + ":framework-wifi-updatable-sources", + ":ike-srcs", + ":updatable-media-srcs", + ], +} + +droidstubs { + name: "android-non-updatable-doc-stubs", + defaults: [ + "android-non-updatable-doc-stubs-defaults", + "module-classpath-stubs-defaults", + ], + args: metalava_framework_docs_args, +} + +droidstubs { + name: "android-non-updatable-doc-stubs-system", + defaults: [ + "android-non-updatable-doc-stubs-defaults", + "module-classpath-stubs-defaults", + ], + args: metalava_framework_docs_args + + " --show-annotation android.annotation.SystemApi\\(client=android.annotation.SystemApi.Client.PRIVILEGED_APPS\\) ", +} + +droidstubs { + name: "android-non-updatable-doc-stubs-module-lib", + defaults: [ + "android-non-updatable-doc-stubs-defaults", + "module-classpath-stubs-defaults", + ], + args: metalava_framework_docs_args + + " --show-annotation android.annotation.SystemApi\\(client=android.annotation.SystemApi.Client.PRIVILEGED_APPS\\) " + + " --show-annotation android.annotation.SystemApi\\(client=android.annotation.SystemApi.Client.MODULE_LIBRARIES\\) ", + generate_stubs: false, // We're only using this module for the annotations.zip output, disable doc-stubs. + write_sdk_values: false, +} + +droidstubs { + name: "android-non-updatable-doc-stubs-system-server", + defaults: [ + "android-non-updatable-doc-stubs-defaults", + "module-classpath-stubs-defaults", + ], + args: metalava_framework_docs_args + + " --show-annotation android.annotation.SystemApi\\(client=android.annotation.SystemApi.Client.PRIVILEGED_APPS\\) " + + " --show-annotation android.annotation.SystemApi\\(client=android.annotation.SystemApi.Client.MODULE_LIBRARIES\\) " + + " --show-annotation android.annotation.SystemApi\\(client=android.annotation.SystemApi.Client.SYSTEM_SERVER\\) ", + generate_stubs: false, // We're only using this module for the annotations.zip output, disable doc-stubs. + write_sdk_values: false, +} + +droidstubs { + name: "framework-doc-stubs", + defaults: ["android-non-updatable-doc-stubs-defaults"], + srcs: [":all-modules-public-stubs-source"], + args: metalava_framework_docs_args, + api_levels_module: "api_versions_public", + aidl: { + include_dirs: [ + "packages/modules/Connectivity/framework/aidl-export", + "packages/modules/Media/apex/aidl/stable", + ], + }, + extensions_info_file: ":sdk-extensions-info", +} + +droidstubs { + name: "framework-doc-system-stubs", + defaults: ["framework-doc-stubs-sources-default"], + args: metalava_framework_docs_args + + " --show-annotation android.annotation.SystemApi\\(client=android.annotation.SystemApi.Client.PRIVILEGED_APPS\\) ", + api_levels_annotations_enabled: true, + api_levels_annotations_dirs: [ + "sdk-dir", + "api-versions-jars-dir", + ], + api_levels_sdk_type: "system", + extensions_info_file: ":sdk-extensions-info", +} + +///////////////////////////////////////////////////////////////////// +// API docs are created from the generated stub source files +// using droiddoc +///////////////////////////////////////////////////////////////////// + +framework_docs_only_args = " -android -manifest $(location :frameworks-base-core-AndroidManifest.xml) " + + "-metalavaApiSince " + + "-werror -lerror -hide 111 -hide 113 -hide 125 -hide 126 -hide 127 -hide 128 " + + "-overview $(location :frameworks-base-java-overview) " + + // Federate Support Library references against local API file. + "-federate SupportLib https://developer.android.com " + + "-federationapi SupportLib $(location :current-support-api) " + + // Federate Support Library references against local API file. + "-federate AndroidX https://developer.android.com " + + "-federationapi AndroidX $(location :current-androidx-api) " + +doc_defaults { + name: "framework-docs-default", + libs: framework_docs_only_libs + [ + "stub-annotations", + "unsupportedappusage", + ], + html_dirs: [ + "docs/html", + ], + knowntags: [ + "docs/knowntags.txt", + ":art.module.public.api{.doctags}", + ], + custom_template: "droiddoc-templates-sdk", + resourcesdir: "docs/html/reference/images/", + resourcesoutdir: "reference/android/images/", + hdf: [ + "dac true", + "sdk.codename O", + "sdk.preview.version 1", + "sdk.version 7.0", + "sdk.rel.id 1", + "sdk.preview 0", + ], + arg_files: [ + ":frameworks-base-core-AndroidManifest.xml", + ":frameworks-base-java-overview", + ":current-support-api", + ":current-androidx-api", + ], + // TODO(b/169090544): remove below aidl includes. + aidl: { + include_dirs: [ + "frameworks/av/aidl", + "frameworks/base/media/aidl", + "frameworks/native/libs/permission/aidl", + ], + }, +} + +doc_defaults { + name: "framework-dokka-docs-default", +} + +droiddoc { + name: "doc-comment-check-docs", + defaults: ["framework-docs-default"], + srcs: [ + ":framework-doc-stubs", + ], + args: framework_docs_only_args + " -referenceonly -parsecomments", + installable: false, +} + +droiddoc { + name: "offline-sdk-docs", + defaults: ["framework-docs-default"], + srcs: [ + ":framework-doc-stubs", + ], + hdf: [ + "android.whichdoc offline", + ], + compat_config: ":global-compat-config", + proofread_file: "offline-sdk-docs-proofread.txt", + args: framework_docs_only_args + " -offlinemode -title \"Android SDK\"", + static_doc_index_redirect: "docs/docs-preview-index.html", +} + +droiddoc { + // Please sync with android-api-council@ before making any changes for the name property below. + // Since there's cron jobs that fetch offline-sdk-referenceonly-docs-docs.zip periodically. + // See b/116221385 for reference. + name: "offline-sdk-referenceonly-docs", + defaults: ["framework-docs-default"], + srcs: [ + ":framework-doc-stubs", + ], + hdf: [ + "android.whichdoc offline", + ], + proofread_file: "offline-sdk-referenceonly-docs-proofread.txt", + args: framework_docs_only_args + " -offlinemode -title \"Android SDK\" -referenceonly", + static_doc_index_redirect: "docs/docs-documentation-redirect.html", + static_doc_properties: "docs/source.properties", +} + +droiddoc { + // Please sync with android-api-council@ before making any changes for the name property below. + // Since there's cron jobs that fetch offline-system-sdk-referenceonly-docs-docs.zip periodically. + // See b/116221385 for reference. + name: "offline-system-sdk-referenceonly-docs", + defaults: ["framework-docs-default"], + srcs: [ + ":framework-doc-system-stubs", + ], + hdf: [ + "android.whichdoc offline", + ], + proofread_file: "offline-system-sdk-referenceonly-docs-proofread.txt", + args: framework_docs_only_args + " -hide 101 -hide 104 -hide 108" + + " -offlinemode -title \"Android System SDK\" -referenceonly", + static_doc_index_redirect: "docs/docs-documentation-redirect.html", + static_doc_properties: "docs/source.properties", +} + +droiddoc { + name: "online-sdk-docs", + defaults: ["framework-docs-default"], + srcs: [ + ":framework-doc-stubs", + ], + hdf: [ + "android.whichdoc online", + "android.hasSamples true", + ], + proofread_file: "online-sdk-docs-proofread.txt", + args: framework_docs_only_args + + " -toroot / -samplegroup Admin " + + " -samplegroup Background " + + " -samplegroup Connectivity " + + " -samplegroup Content " + + " -samplegroup Input " + + " -samplegroup Media " + + " -samplegroup Notification " + + " -samplegroup RenderScript " + + " -samplegroup Security " + + " -samplegroup Sensors " + + " -samplegroup System " + + " -samplegroup Testing " + + " -samplegroup UI " + + " -samplegroup Views " + + " -samplegroup Wearable -samplesdir development/samples/browseable ", +} + +droiddoc { + name: "online-system-api-sdk-docs", + defaults: ["framework-docs-default"], + srcs: [ + ":framework-doc-system-stubs", + ], + hdf: [ + "android.whichdoc online", + "android.hasSamples true", + ], + proofread_file: "online-system-api-sdk-docs-proofread.txt", + args: framework_docs_only_args + + " -referenceonly " + + " -title \"Android SDK - Including system APIs.\" " + + " -hide 101 " + + " -hide 104 " + + " -hide 108 " + + " -toroot / -samplegroup Admin " + + " -samplegroup Background " + + " -samplegroup Connectivity " + + " -samplegroup Content " + + " -samplegroup Input " + + " -samplegroup Media " + + " -samplegroup Notification " + + " -samplegroup RenderScript " + + " -samplegroup Security " + + " -samplegroup Sensors " + + " -samplegroup System " + + " -samplegroup Testing " + + " -samplegroup UI " + + " -samplegroup Views " + + " -samplegroup Wearable -samplesdir development/samples/browseable ", + installable: false, +} + +droiddoc { + name: "ds-docs-java", + defaults: ["framework-docs-default"], + srcs: [ + ":framework-doc-stubs", + ], + hdf: [ + "android.whichdoc online", + "android.hasSamples true", + ], + proofread_file: "ds-docs-proofread.txt", + args: framework_docs_only_args + + " -toroot / -yamlV2 -samplegroup Admin " + + " -samplegroup Background " + + " -samplegroup Connectivity " + + " -samplegroup Content " + + " -samplegroup Input " + + " -samplegroup Media " + + " -samplegroup Notification " + + " -samplegroup RenderScript " + + " -samplegroup Security " + + " -samplegroup Sensors " + + " -samplegroup System " + + " -samplegroup Testing " + + " -samplegroup UI " + + " -samplegroup Views " + + " -samplegroup Wearable -devsite -samplesdir development/samples/browseable ", +} + +droiddoc { + name: "ds-docs-kt", + defaults: ["framework-dokka-docs-default"], + srcs: [ + ":framework-doc-stubs", + ], + args: "-noJdkLink -links https://kotlinlang.org/api/latest/jvm/stdlib/^external/dokka/package-list " + + "-noStdlibLink", + proofread_file: "ds-dokka-proofread.txt", + dokka_enabled: true, +} + +java_genrule { + name: "ds-docs", + tools: [ + "zip2zip", + "merge_zips", + ], + srcs: [ + ":ds-docs-java{.docs.zip}", + ":ds-docs-kt{.docs.zip}", + ], + out: ["ds-docs.zip"], + dist: { + targets: ["docs"], + }, + cmd: "$(location zip2zip) -i $(location :ds-docs-kt{.docs.zip}) -o $(genDir)/ds-docs-kt-moved.zip **/*:en/reference/kotlin && " + + "$(location merge_zips) $(out) $(location :ds-docs-java{.docs.zip}) $(genDir)/ds-docs-kt-moved.zip", +} + +java_genrule { + name: "ds-docs-switched", + tools: [ + "switcher4", + "soong_zip", + ], + srcs: [ + ":ds-docs-java{.docs.zip}", + ":ds-docs-kt{.docs.zip}", + ], + out: ["ds-docs-switched.zip"], + dist: { + targets: ["docs"], + }, + cmd: "unzip -q $(location :ds-docs-java{.docs.zip}) -d $(genDir) && " + + "unzip -q $(location :ds-docs-kt{.docs.zip}) -d $(genDir)/en/reference/kotlin && " + + "SWITCHER=$$(cd $$(dirname $(location switcher4)) && pwd)/$$(basename $(location switcher4)) && " + + "(cd $(genDir)/en/reference && $$SWITCHER --work platform) > /dev/null && " + + "$(location soong_zip) -o $(out) -C $(genDir) -D $(genDir)", +} + +droiddoc { + name: "ds-static-docs", + defaults: ["framework-docs-default"], + srcs: [ + ":framework-doc-stubs", + ], + hdf: [ + "android.whichdoc online", + ], + args: framework_docs_only_args + + " -staticonly " + + " -toroot / " + + " -devsite " + + " -ignoreJdLinks ", +} + +droiddoc { + name: "ds-ref-navtree-docs", + defaults: ["framework-docs-default"], + srcs: [ + ":framework-doc-stubs", + ], + hdf: [ + "android.whichdoc online", + ], + args: framework_docs_only_args + + " -toroot / " + + " -atLinksNavtree " + + " -navtreeonly ", +} + +droiddoc { + name: "online-sdk-dev-docs", + defaults: ["framework-docs-default"], + srcs: [ + ":framework-doc-stubs", + ], + hdf: [ + "android.whichdoc online", + "android.hasSamples true", + ], + proofread_file: "online-sdk-dev-docs-proofread.txt", + args: framework_docs_only_args + + " -toroot / -samplegroup Admin " + + " -samplegroup Background " + + " -samplegroup Connectivity " + + " -samplegroup Content " + + " -samplegroup Input " + + " -samplegroup Media " + + " -samplegroup Notification " + + " -samplegroup RenderScript " + + " -samplegroup Security " + + " -samplegroup Sensors " + + " -samplegroup System " + + " -samplegroup Testing " + + " -samplegroup UI " + + " -samplegroup Views " + + " -samplegroup Wearable -samplesdir development/samples/browseable ", +} + +droiddoc { + name: "hidden-docs", + defaults: ["framework-docs-default"], + srcs: [ + ":framework-doc-stubs", + ], + proofread_file: "hidden-docs-proofread.txt", + args: framework_docs_only_args + + " -referenceonly " + + " -title \"Android SDK - Including hidden APIs.\"", +} -- cgit v1.2.3-59-g8ed1b