From bb2f9200273646a1cfcabf56f7c038e076a5e16c Mon Sep 17 00:00:00 2001 From: Peter Collins Date: Wed, 15 Jun 2022 13:20:33 -0400 Subject: [PATCH] [Mono.Android] Generate docs for any API level The `_UpdateExternalDocumentation` target has been updated to allow API docs to be updated against any API level. Latest stable versions will still be used by default, however the `$(AndroidApiLevel)`, `$(AndroidPlatformId)`, and `$(AndroidFrameworkVersion)` properties can now be set if needed. This will let us update the current API 31 docs without having to release an API 32 update. The api docs pipeline has been updated to allow these properties to be set at queue time, and it will now upload a `.diff` file rather than the entire docs folder. --- Makefile | 3 ++ .../automation/azure-pipelines-apidocs.yaml | 47 ++++++++++++------- src/Mono.Android/Mono.Android.targets | 42 ++++++++++++----- 3 files changed, 62 insertions(+), 30 deletions(-) diff --git a/Makefile b/Makefile index dbe059b22f7..952d405a564 100644 --- a/Makefile +++ b/Makefile @@ -223,3 +223,6 @@ APK_SIZES_REFERENCE_DIR=tests/apk-sizes-reference update-apk-sizes-reference: -mkdir -p $(APK_SIZES_REFERENCE_DIR) cp -v *values-$(CONFIGURATION).csv $(APK_SIZES_REFERENCE_DIR)/ + +update-api-docs: + $(call DOTNET_BINLOG,update-api-docs) -t:UpdateExternalDocumentation src/Mono.Android/Mono.Android.csproj diff --git a/build-tools/automation/azure-pipelines-apidocs.yaml b/build-tools/automation/azure-pipelines-apidocs.yaml index cef78b3f7f3..65a70ed672f 100644 --- a/build-tools/automation/azure-pipelines-apidocs.yaml +++ b/build-tools/automation/azure-pipelines-apidocs.yaml @@ -8,6 +8,22 @@ trigger: none pr: none +parameters: +- name: apiLevel + displayName: AndroidApiLevel property value + type: string + default: 31 + +- name: platformId + displayName: AndroidPlatformId property value + type: string + default: 31 + +- name: frameworkVersion + displayName: AndroidFrameworkVersion property value + type: string + default: v12.0 + # Global variables variables: - template: yaml-templates/variables.yaml @@ -20,7 +36,8 @@ stages: - job: mac_build_update_docs displayName: Update API Docs pool: - vmImage: macOS-11 + name: VSEng-Xamarin-RedmondMac-Android-Untrusted + demands: macOS.Name -equals Monterey timeoutInMinutes: 120 workspace: clean: all @@ -47,28 +64,22 @@ stages: workingDirectory: $(Build.SourcesDirectory) displayName: make prepare - - task: MSBuild@1 - displayName: build jnienv-gen.csproj - inputs: - solution: $(Build.SourcesDirectory)/external/Java.Interop/build-tools/jnienv-gen/jnienv-gen.csproj - configuration: $(XA.Build.Configuration) - msbuildArguments: /restore - - - task: MSBuild@1 - displayName: update android-api-docs - inputs: - solution: $(Build.SourcesDirectory)/src/Mono.Android/Mono.Android.csproj - configuration: $(XA.Build.Configuration) - msbuildArguments: /restore /t:UpdateExternalDocumentation + - script: make update-api-docs CONFIGURATION=$(XA.Build.Configuration) MSBUILD_ARGS='-p:AndroidApiLevel=${{ parameters.apiLevel }} -p:AndroidPlatformId=${{ parameters.platformId }} -p:AndroidFrameworkVersion=${{ parameters.frameworkVersion }}' + workingDirectory: $(Build.SourcesDirectory) + displayName: make update-api-docs - template: yaml-templates/upload-results.yaml parameters: - xaSourcePath: $(System.DefaultWorkingDirectory)/xamarin-android artifactName: Build Results - API Docs Update includeBuildResults: true + - script: > + mkdir -p $(Build.StagingDirectory)/api-doc-diff && + ln $(Build.SourcesDirectory)/bin/Build$(XA.Build.Configuration)/UpdateApiDocs*.diff $(Build.StagingDirectory)/api-doc-diff/ + displayName: copy api docs diff + - task: PublishPipelineArtifact@1 - displayName: upload Mono.Android docs + displayName: upload api docs diff inputs: - artifactName: Mono.Android Docs - targetPath: $(Build.SourcesDirectory)/external/android-api-docs/docs/Mono.Android/en/ + artifactName: Api Docs Diff + targetPath: $(Build.StagingDirectory)/api-doc-diff diff --git a/src/Mono.Android/Mono.Android.targets b/src/Mono.Android/Mono.Android.targets index 735a8761d19..7a74f0877b2 100644 --- a/src/Mono.Android/Mono.Android.targets +++ b/src/Mono.Android/Mono.Android.targets @@ -75,14 +75,14 @@ <_JavaSourceUtilsJar>$(MicrosoftAndroidSdkOutDir)java-source-utils.jar - <_AndroidStableSrcDir>$(AndroidSdkDirectory)\platforms\android-$(AndroidLatestStableApiLevel)\src + <_AndroidSrcDir>$(AndroidSdkDirectory)\platforms\android-$(AndroidApiLevel)\src <_AndroidJavadocXml>..\..\bin\Build$(Configuration)\android-javadoc.xml <_Doclink Include="--doc-copyright" /> @@ -95,11 +95,11 @@ <_Doclink Include="https://developer.android.com/" /> - <_AndroidSources Include="$(_AndroidStableSrcDir)\android\**\*.java" /> - <_AndroidSources Include="$(_AndroidStableSrcDir)\java\**\*.java" /> - <_AndroidSources Include="$(_AndroidStableSrcDir)\javax\**\*.java" /> - <_AndroidSources Include="$(_AndroidStableSrcDir)\org\**\*.java" /> - <_AndroidSources Remove="$(_AndroidStableSrcDir)\**\*.annotated.java" /> + <_AndroidSources Include="$(_AndroidSrcDir)\android\**\*.java" /> + <_AndroidSources Include="$(_AndroidSrcDir)\java\**\*.java" /> + <_AndroidSources Include="$(_AndroidSrcDir)\javax\**\*.java" /> + <_AndroidSources Include="$(_AndroidSrcDir)\org\**\*.java" /> + <_AndroidSources Remove="$(_AndroidSrcDir)\**\*.annotated.java" /> <_Filenames>$(IntermediateOutputPath)\java-sources.txt @@ -111,7 +111,7 @@ /> <_JSIArg Include="-v" /> - <_JSIArg Include="--source "$(_AndroidStableSrcDir)"" /> + <_JSIArg Include="--source "$(_AndroidSrcDir)"" /> <_JSIArg Include="--output-javadoc "$(_AndroidJavadocXml)"" /> <_JSIArg Include="@$(_Filenames)" /> @@ -289,16 +289,24 @@ - <_Binlog>$(MSBuildThisFileDirectory)../../bin/Build$(Configuration)/UpdateExternalDocumentation-$([System.DateTime]::Now.ToString ("yyyyMMddTHHmmss")).binlog + <_Binlog>$(MSBuildThisFileDirectory)../../bin/Build$(Configuration)/UpdateApiDocs-$([System.DateTime]::Now.ToString ("yyyyMMddTHHmmss")).binlog + + <_BuildProps Include="-p:IncludeAndroidJavadoc=True" /> + <_BuildProps Include="-p:TargetFramework=monoandroid10" /> + + <_BuildProps Include="-p:AndroidApiLevel=$(AndroidApiLevel)" /> + <_BuildProps Include="-p:AndroidPlatformId=$(AndroidPlatformId)" /> + <_BuildProps Include="-p:AndroidFrameworkVersion=$(AndroidFrameworkVersion)" /> + @@ -352,5 +360,15 @@ WorkingDirectory="$(MSBuildThisFileDirectory)" /> - + + + + <_DiffFile>$(XamarinAndroidSourcePath)bin/Build$(Configuration)/UpdateApiDocs$([System.DateTime]::Now.ToString ("yyyyMMddTHHmmss")).diff + + + +