[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.
dotnet · Jun 15, 2022 · bb2f920 · bb2f920
1 parent c59b591
commit bb2f920
Show file tree

Hide file tree

Showing 3 changed files with 62 additions and 30 deletions.
diff --git 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
@@ -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
@@ -75,14 +75,14 @@
   <!-- Pulls documentation from JavaDoc -->
   <PropertyGroup>
     <_JavaSourceUtilsJar>$(MicrosoftAndroidSdkOutDir)java-source-utils.jar</_JavaSourceUtilsJar>
-    <_AndroidStableSrcDir>$(AndroidSdkDirectory)\platforms\android-$(AndroidLatestStableApiLevel)\src</_AndroidStableSrcDir>
+    <_AndroidSrcDir>$(AndroidSdkDirectory)\platforms\android-$(AndroidApiLevel)\src</_AndroidSrcDir>
     <_AndroidJavadocXml>..\..\bin\Build$(Configuration)\android-javadoc.xml</_AndroidJavadocXml>
   </PropertyGroup>
 
   <Target Name="_BuildAndroidJavadocXml"
       Condition=" '$(IncludeAndroidJavadoc)' == 'True' "
       BeforeTargets="CoreCompile"
-      Inputs="$(MSBuildThisFile);$(_AndroidStableSrcDir)\source.properties;$(_JavaSourceUtilsJar)"
+      Inputs="$(MSBuildThisFile);$(_AndroidSrcDir)\source.properties;$(_JavaSourceUtilsJar)"
       Outputs="$(_AndroidJavadocXml)">
     <ItemGroup>
       <_Doclink Include="--doc-copyright" />
@@ -95,11 +95,11 @@
       <_Doclink Include="https://developer.android.com/" />
     </ItemGroup>
     <ItemGroup>
-      <_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" />
     </ItemGroup>
     <PropertyGroup>
       <_Filenames>$(IntermediateOutputPath)\java-sources.txt</_Filenames>
@@ -111,7 +111,7 @@
     />
     <ItemGroup>
       <_JSIArg Include="-v" />
-      <_JSIArg Include="--source &quot;$(_AndroidStableSrcDir)&quot;" />
+      <_JSIArg Include="--source &quot;$(_AndroidSrcDir)&quot;" />
       <_JSIArg Include="--output-javadoc &quot;$(_AndroidJavadocXml)&quot;" />
       <_JSIArg Include="@$(_Filenames)" />
     </ItemGroup>
@@ -289,16 +289,24 @@
   <Target Name="UpdateExternalDocumentation">
     <MSBuild Projects="$(MSBuildThisFileDirectory)Mono.Android.csproj"
         Properties="TargetFramework=monoandroid10"
-        Targets="_UpdateExternalDocumentation;_RunMdoc"
+        Targets="_UpdateExternalDocumentation;_RunMdoc;_GenerateApiDocsDiff"
     />
   </Target>
   <Target Name="_UpdateExternalDocumentation">
     <RemoveDir Directories="$(BaseIntermediateOutputPath)" />
     <PropertyGroup>
-      <_Binlog>$(MSBuildThisFileDirectory)../../bin/Build$(Configuration)/UpdateExternalDocumentation-$([System.DateTime]::Now.ToString ("yyyyMMddTHHmmss")).binlog</_Binlog>
+      <_Binlog>$(MSBuildThisFileDirectory)../../bin/Build$(Configuration)/UpdateApiDocs-$([System.DateTime]::Now.ToString ("yyyyMMddTHHmmss")).binlog</_Binlog>
     </PropertyGroup>
+    <ItemGroup>
+      <_BuildProps Include="-p:IncludeAndroidJavadoc=True" />
+      <_BuildProps Include="-p:TargetFramework=monoandroid10" />
+      <!-- Override these properties to generate docs against a specific API level -->
+      <_BuildProps Include="-p:AndroidApiLevel=$(AndroidApiLevel)" />
+      <_BuildProps Include="-p:AndroidPlatformId=$(AndroidPlatformId)" />
+      <_BuildProps Include="-p:AndroidFrameworkVersion=$(AndroidFrameworkVersion)" />
+    </ItemGroup>
     <Exec
-        Command="dotnet build -v:n -c $(Configuration) -p:IncludeAndroidJavadoc=True -bl:$(_Binlog)"
+        Command="&quot;$(DotNetPreviewTool)&quot; build -v:n -c $(Configuration) -bl:$(_Binlog) @(_BuildProps, ' ')"
         IgnoreStandardErrorWarningFormat="True"
         WorkingDirectory="$(MSBuildThisFileDirectory)"
     />
@@ -352,5 +360,15 @@
         WorkingDirectory="$(MSBuildThisFileDirectory)"
     />
   </Target>
-
+
+  <Target Name="_GenerateApiDocsDiff">
+    <PropertyGroup>
+      <_DiffFile>$(XamarinAndroidSourcePath)bin/Build$(Configuration)/UpdateApiDocs$([System.DateTime]::Now.ToString ("yyyyMMddTHHmmss")).diff</_DiffFile>
+    </PropertyGroup>
+    <Exec
+        Command="git diff --output=&quot;$(_DiffFile)&quot;"
+        WorkingDirectory="$(XamarinAndroidSourcePath)external/android-api-docs"
+    />
+  </Target>
+
 </Project>