ApiDocs.bp

// 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",
]

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.
        "test-base/src/**/*.java",
        "test-mock/src/**/*.java",
        "test-runner/src/**/*.java",
    ],
    libs: framework_docs_only_libs,
    create_doc_stubs: true,
    write_sdk_values: true,
}

stubs_defaults {
    name: "framework-doc-stubs-default",
    srcs: [
        ":android-non-updatable-stub-sources",

        // Module sources
        ":art.module.public.api{.public.stubs.source}",
        ":conscrypt.module.public.api{.public.stubs.source}",
        ":i18n.module.public.api{.public.stubs.source}",

        // No longer part of the stubs, but are included in the docs.
        ":android-test-base-sources",
        ":android-test-mock-sources",
        ":android-test-runner-sources",
    ],
    arg_files: [
        "core/res/AndroidManifest.xml",
    ],
    libs: framework_docs_only_libs,
    create_doc_stubs: true,
    annotations_enabled: true,
    filter_packages: packages_to_document,
    api_levels_annotations_enabled: true,
    api_levels_annotations_dirs: [
        "sdk-dir",
        "api-versions-jars-dir",
    ],
    previous_api: ":android.api.public.latest",
    merge_annotations_dirs: [
        "metalava-manual",
    ],
    write_sdk_values: true,
    // TODO(b/169090544): remove below aidl includes.
    aidl: {
        local_include_dirs: ["media/aidl"],
        include_dirs: [
            "frameworks/av/aidl",
            "frameworks/native/libs/permission/aidl",
        ],
    },
}

// Defaults module for doc-stubs targets that use module source code as input.
// This is the default/normal.
stubs_defaults {
    name: "framework-doc-stubs-sources-default",
    defaults: ["framework-doc-stubs-default"],
    srcs: [
        ":framework-appsearch-sources",
        ":framework-connectivity-sources",
        ":framework-graphics-srcs",
        ":framework-mediaprovider-sources",
        ":framework-permission-sources",
        ":framework-permission-s-sources",
        ":framework-scheduling-sources",
        ":framework-sdkextensions-sources",
        ":framework-statsd-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"],
    args: metalava_framework_docs_args,
}

droidstubs {
    name: "android-non-updatable-doc-stubs-system",
    defaults: ["android-non-updatable-doc-stubs-defaults"],
    args: metalava_framework_docs_args +
        " --show-annotation android.annotation.SystemApi\\(client=android.annotation.SystemApi.Client.PRIVILEGED_APPS\\) ",
}

droidstubs {
    name: "framework-doc-stubs",
    defaults: ["framework-doc-stubs-sources-default"],
    args: metalava_framework_docs_args,
}

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_sdk_type: "system",
}

// Experimental target building doc stubs with module stub source code as input.
// This is intended to eventually replace framework-doc-stubs, once all diffs
// have been eliminated.
droidstubs {
    name: "framework-doc-stubs-module-stubs",
    defaults: ["framework-doc-stubs-default"],
    args: metalava_framework_docs_args,
    srcs: [
        ":android.net.ipsec.ike{.public.stubs.source}",
        ":framework-appsearch{.public.stubs.source}",
        ":framework-connectivity{.public.stubs.source}",
        ":framework-graphics{.public.stubs.source}",
        ":framework-media{.public.stubs.source}",
        ":framework-mediaprovider{.public.stubs.source}",
        ":framework-permission{.public.stubs.source}",
        ":framework-permission-s{.public.stubs.source}",
        ":framework-scheduling{.public.stubs.source}",
        ":framework-sdkextensions{.public.stubs.source}",
        ":framework-statsd{.public.stubs.source}",
        ":framework-tethering{.public.stubs.source}",
        ":framework-uwb{.public.stubs.source}",
        ":framework-wifi{.public.stubs.source}",
    ],
    aidl: {
        local_include_dirs: [
            "apex/media/aidl/stable",
        ],
        include_dirs: [
            "packages/modules/Connectivity/framework/aidl-export",
        ],
    },
}

// This produces the same annotations.zip as framework-doc-stubs, but by using
// outputs from individual modules instead of all the source code.
genrule {
    name: "sdk-annotations.zip",
    srcs: [
        ":android-non-updatable-doc-stubs{.annotations.zip}",

        // Conscrypt and i18n currently do not enable annotations
        // ":conscrypt.module.public.api{.public.annotations.zip}",
        // ":i18n.module.public.api{.public.annotations.zip}",

        // Modules that enable annotations below
        ":android.net.ipsec.ike{.public.annotations.zip}",
        ":art.module.public.api{.public.annotations.zip}",
        ":framework-appsearch{.public.annotations.zip}",
        ":framework-connectivity{.public.annotations.zip}",
        ":framework-graphics{.public.annotations.zip}",
        ":framework-media{.public.annotations.zip}",
        ":framework-mediaprovider{.public.annotations.zip}",
        ":framework-permission{.public.annotations.zip}",
        ":framework-permission-s{.public.annotations.zip}",
        ":framework-scheduling{.public.annotations.zip}",
        ":framework-sdkextensions{.public.annotations.zip}",
        ":framework-statsd{.public.annotations.zip}",
        ":framework-tethering{.public.annotations.zip}",
        ":framework-uwb{.public.annotations.zip}",
        ":framework-wifi{.public.annotations.zip}",
    ],
    out: ["annotations.zip"],
    tools: [
        "merge_annotation_zips",
        "soong_zip",
    ],
    cmd: "$(location merge_annotation_zips) $(genDir)/out $(in) && " +
        "$(location soong_zip) -o $(out) -C $(genDir)/out -D $(genDir)/out",
}

/////////////////////////////////////////////////////////////////////
// API docs are created from the generated stub source files
// using droiddoc
/////////////////////////////////////////////////////////////////////

framework_docs_only_args = " -android -manifest $(location core/res/AndroidManifest.xml) " +
    "-werror -lerror -hide 111 -hide 113 -hide 125 -hide 126 -hide 127 -hide 128 " +
    "-overview $(location core/java/overview.html) " +
    // 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: [
        "core/res/AndroidManifest.xml",
        "core/java/overview.html",
        ":current-support-api",
        ":current-androidx-api",
    ],
    // TODO(b/169090544): remove below aidl includes.
    aidl: {
        local_include_dirs: ["media/aidl"],
        include_dirs: [
            "frameworks/av/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-proofrerad.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-proofrerad.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-proofrerad.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-proofrerad.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-proofrerad.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-proofrerad.txt",
    args: framework_docs_only_args +
        " -toroot / -yamlV2 -metalavaApiSince -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-proofrerad.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-proofrerad.txt",
    args: framework_docs_only_args +
        " -referenceonly " +
        " -title \"Android SDK - Including hidden APIs.\"",
}