[ci] Add pipeline for updating api docs (#6460)

Add a new `azure-pipelines-apidocs.yaml` pipeline that can be used to
update the `Mono.Android` API docs in the
[xamarin/android-api-docs][0] repository.  We will now only build
`src/Mono.Android` with generated JavaDoc XML when running this new
pipeline.

The new pipeline will run the `<UpdateExternalDocumentation/>` target
and upload the contents of `/android-api-docs/docs/Mono.Android/en/`
as a build artifact.  These updated docs can be downloaded for manual
review and pull request creation.

The .NET 6 packs have been updated to include the same
`Mono.Android.xml` docs that are bundled into the traditional Windows
`.vsix` installer.  These docs are generated from the content of
`external/android-api-docs` when the `<AssembleApiDocs/>` installer
target is run.

[0]: https://github.com/xamarin/android-api-docs

Author: pjcollins

Configuration.props

@@ -53,6 +53,7 @@
     <AutoProvisionUsesSudo Condition=" '$(AutoProvisionUsesSudo)' == '' ">False</AutoProvisionUsesSudo>
     <_XABinRelativeInstallPrefix>lib\xamarin.android</_XABinRelativeInstallPrefix>
     <XAInstallPrefix Condition=" '$(XAInstallPrefix)' == '' ">$(MSBuildThisFileDirectory)bin\$(Configuration)\$(_XABinRelativeInstallPrefix)\</XAInstallPrefix>
+    <_MonoAndroidNETOutputDir>$(XAInstallPrefix)xbuild-frameworks\Microsoft.Android\net6.0\</_MonoAndroidNETOutputDir>
     <MingwDependenciesRootDirectory Condition=" '$(MingwDependenciesRootDirectory)' == '' ">$(MSBuildThisFileDirectory)\bin\Build$(Configuration)\mingw-deps</MingwDependenciesRootDirectory>
     <HostCc Condition=" '$(HostCc)' == '' ">$(HostCc64)</HostCc>
     <HostCxx Condition=" '$(HostCxx)' == '' ">$(HostCxx64)</HostCxx>

build-tools/automation/azure-pipelines-apidocs.yaml

@@ -0,0 +1,74 @@
+# Pipeline for updating and uploading android-api-docs/docs/Mono.Android/en/*
+# https://dev.azure.com/devdiv/DevDiv/_build?definitionId=15262
+
+# This pipeline can be manually ran against a given branch to generate a new set of Mono.Android docs.
+# The `Mono.Android Docs` artifact can be downloaded and copied into a local android-api-docs checkout
+# for manual review and pull request creation.
+
+trigger: none
+pr: none
+
+# Global variables
+variables:
+- template: yaml-templates/variables.yaml
+
+stages:
+- stage: mac_build
+  displayName: Build
+  dependsOn: []
+  jobs:
+  - job: mac_build_update_docs
+    displayName: Update API Docs
+    pool:
+      vmImage: macOS-11
+    timeoutInMinutes: 120
+    workspace:
+      clean: all
+    steps:
+    - checkout: self
+      submodules: recursive
+
+    - script: echo "##vso[task.setvariable variable=JI_JAVA_HOME]$HOME/Library/Android/$(XA.Jdk11.Folder)"
+      displayName: set JI_JAVA_HOME
+
+    - template: yaml-templates/use-dot-net.yaml
+
+    - task: NuGetAuthenticate@0
+      displayName: authenticate with azure artifacts
+      inputs:
+        forceReinstallCredentialProvider: true
+
+    - template: yaml-templates/run-xaprepare.yaml
+      parameters:
+        displayName: update mono
+        arguments: --s=UpdateMono
+
+    - script: make prepare CONFIGURATION=$(XA.Build.Configuration) PREPARE_CI=1 PREPARE_AUTOPROVISION=1
+      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
+
+    - template: yaml-templates/upload-results.yaml
+      parameters:
+        xaSourcePath: $(System.DefaultWorkingDirectory)/xamarin-android
+        artifactName: Build Results - API Docs Update
+        includeBuildResults: true
+
+    - task: PublishPipelineArtifact@1
+      displayName: upload Mono.Android docs
+      inputs:
+        artifactName: Mono.Android Docs
+        targetPath: $(Build.SourcesDirectory)/external/android-api-docs/docs/Mono.Android/en/

build-tools/automation/azure-pipelines.yaml

@@ -44,8 +44,6 @@ variables:
   value: $[or(eq(variables['XA.RunAllTests'], true), eq(variables['IsMonoBranch'], true))]
 - name: DotNetNUnitCategories
   value: '& TestCategory != DotNetIgnore & TestCategory != HybridAOT & TestCategory != ProfiledAOT & TestCategory != MkBundle & TestCategory != MonoSymbolicate & TestCategory != PackagesConfig & TestCategory != StaticProject & TestCategory != Debugger & TestCategory != SystemApplication'
-- name: CONVERT_JAVADOC_TO_XMLDOC
-  value: $[ne(variables['Build.DefinitionName'], 'Xamarin.Android-PR')]
 - ${{ if and(eq(variables['Build.DefinitionName'], 'Xamarin.Android'), ne(variables['Build.Reason'], 'PullRequest')) }}:
   - name: MicroBuildSignType
     value: Real

build-tools/create-packs/Directory.Build.targets

@@ -13,10 +13,6 @@
   <UsingTask TaskName="GenerateBuildManifest" AssemblyFile="$(_MicrosoftDotNetBuildTasksFeedTaskDir)Microsoft.DotNet.Build.Tasks.Feed.dll" />
   <UsingTask TaskName="Xamarin.Android.BuildTools.PrepTasks.ReplaceFileContents" AssemblyFile="$(PrepTasksAssembly)" />
 
-  <PropertyGroup>
-    <_MonoAndroidNETOutputDir>$(XAInstallPrefix)xbuild-frameworks\Microsoft.Android\net6.0\</_MonoAndroidNETOutputDir>
-  </PropertyGroup>
-
   <!-- https://github.com/dotnet/runtime/blob/0647ec314948904319da5eb15e9931f7c85ed1e2/src/installer/pkg/projects/Directory.Build.targets#L281 -->
   <!-- TODO: Generate PlatformManifest.txt files? -->
   <Target Name="_GenerateFrameworkListFile" >

build-tools/create-packs/Microsoft.Android.Ref.proj

@@ -25,7 +25,7 @@ by projects that use the Microsoft.Android framework in .NET 5.
   </PropertyGroup>
 
   <Target Name="_GetTargetingPackItems"
-      DependsOnTargets="_GetLicense">
+      DependsOnTargets="AssembleApiDocs;_GetLicense">
     <PropertyGroup>
       <FrameworkListFile>$(IntermediateOutputPath)FrameworkList.xml</FrameworkListFile>
     </PropertyGroup>
@@ -40,11 +40,7 @@ by projects that use the Microsoft.Android framework in .NET 5.
     <ItemGroup>
       <_PackageFiles Include="@(_AndroidRefPackAssemblies)" PackagePath="$(_AndroidRefPackAssemblyPath)" TargetPath="$(_AndroidRefPackAssemblyPath)" />
       <_PackageFiles Include="$(_MonoAndroidNETOutputDir)Java.Interop.xml" PackagePath="$(_AndroidRefPackAssemblyPath)" />
-      <_PackageFiles
-          Condition=" '$(CONVERT_JAVADOC_TO_XMLDOC)' == 'true' "
-          Include="$(_MonoAndroidNETOutputDir)Mono.Android.xml"
-          PackagePath="$(_AndroidRefPackAssemblyPath)"
-      />
+      <_PackageFiles Include="$(_MonoAndroidNETOutputDir)Mono.Android.xml" PackagePath="$(_AndroidRefPackAssemblyPath)" />
       <_PackageFiles Include="$(_MonoAndroidNETOutputDir)mono.android.jar" PackagePath="$(_AndroidRefPackAssemblyPath)" />
       <_PackageFiles Include="$(_MonoAndroidNETOutputDir)mono.android.dex" PackagePath="$(_AndroidRefPackAssemblyPath)" />
       <_PackageFiles Include="$(_MonoAndroidNETOutputDir)AndroidApiInfo.xml" PackagePath="$(_AndroidRefPackAssemblyPath)" />

build-tools/installers/create-installers.targets

@@ -52,8 +52,13 @@
   <Target Name="_GenerateMsxDocXmls"
       DependsOnTargets="_FindFrameworkDirs;_FindDocSourceFiles"
       Inputs="@(_MsxDocSourceFile)"
-      Outputs="@(_MsxDocAssembly->'$(_LatestStableFrameworkDir)%(Identity).xml')">
+      Outputs="@(_MsxDocAssembly->'$(_LatestStableFrameworkDir)%(Identity).xml');@(_MsxDocAssembly->'$(_MonoAndroidNETOutputDir)%(Identity).xml')">
     <Exec Command="$(ManagedRuntime) &quot;$(MSBuildSrcDir)mdoc.exe&quot; --debug export-msxdoc -o &quot;$(_LatestStableFrameworkDir)%(_MsxDocAssembly.Identity).xml&quot; &quot;%(_MsxDocAssembly.SourceDir)&quot;" />
+    <Copy
+        SourceFiles="$(_LatestStableFrameworkDir)%(_MsxDocAssembly.Identity).xml"
+        DestinationFolder="$(_MonoAndroidNETOutputDir)"
+    />
+    <Touch Files="@(_MsxDocAssembly->'$(_LatestStableFrameworkDir)%(Identity).xml');@(_MsxDocAssembly->'$(_MonoAndroidNETOutputDir)%(Identity).xml')" />
   </Target>
   <Target Name="_GenerateMsxDocXmlRedirects"
       DependsOnTargets="_FindFrameworkDirs"

src/Mono.Android/Mono.Android.csproj

@@ -24,16 +24,6 @@
     <EnableSingleFileAnalyzer>true</EnableSingleFileAnalyzer>
   </PropertyGroup>
 
-  <PropertyGroup>
-    <IncludeAndroidJavadoc Condition=" '$(IncludeAndroidJavadoc)' == '' And '$(CONVERT_JAVADOC_TO_XMLDOC)' == 'true' And ('$(AndroidFrameworkVersion)' == '$(AndroidLatestStableFrameworkVersion)' or '$(TargetFramework)' != 'monoandroid10')">True</IncludeAndroidJavadoc>
-    <AndroidJavadocVerbosity Condition=" '$(AndroidJavadocVerbosity)' == '' ">intellisense</AndroidJavadocVerbosity>
-  </PropertyGroup>
-
-  <PropertyGroup Condition=" '$(IncludeAndroidJavadoc)' == 'True' ">
-    <DocumentationFile>$(OutputPath)Mono.Android.xml</DocumentationFile>
-    <NoWarn>$(NoWarn);CS1572;CS1573;CS1574;CS1584;CS1587;CS1591;CS1658;</NoWarn>
-  </PropertyGroup>
-
   <PropertyGroup Condition=" '$(TargetFramework)' == 'monoandroid10' ">
     <TargetFrameworkIdentifier>MonoAndroid</TargetFrameworkIdentifier>
     <TargetFrameworkVersion>v1.0</TargetFrameworkVersion>
@@ -46,12 +36,8 @@
     <OutputPath>$(XAInstallPrefix)xbuild-frameworks\Microsoft.Android\$(TargetFramework)\</OutputPath>
   </PropertyGroup>
 
-  <PropertyGroup>
-    <IncludeAndroidJavadoc Condition=" '$(IncludeAndroidJavadoc)' == '' And '$(CONVERT_JAVADOC_TO_XMLDOC)' == 'true' And '$(AndroidFrameworkVersion)' == '$(AndroidLatestStableFrameworkVersion)'">True</IncludeAndroidJavadoc>
-    <AndroidJavadocVerbosity Condition=" '$(AndroidJavadocVerbosity)' == '' ">intellisense+extraremarks</AndroidJavadocVerbosity>
-  </PropertyGroup>
-
   <PropertyGroup Condition=" '$(IncludeAndroidJavadoc)' == 'True' ">
+    <AndroidJavadocVerbosity Condition=" '$(AndroidJavadocVerbosity)' == '' ">intellisense+extraremarks</AndroidJavadocVerbosity>
     <DocumentationFile>$(OutputPath)Mono.Android.xml</DocumentationFile>
     <NoWarn>$(NoWarn);CS1572;CS1573;CS1574;CS1584;CS1587;CS1591;CS1658;</NoWarn>
   </PropertyGroup>

src/Mono.Android/Mono.Android.targets

@@ -282,7 +282,7 @@
   <Target Name="_UpdateExternalDocumentation">
     <RemoveDir Directories="$(BaseIntermediateOutputPath)" />
     <PropertyGroup>
-      <_Binlog>UpdateExternalDocumentation-$([System.DateTime]::Now.ToString ("yyyyMMddTHHmmss")).binlog</_Binlog>
+      <_Binlog>$(MSBuildThisFileDirectory)../../bin/Build$(Configuration)/UpdateExternalDocumentation-$([System.DateTime]::Now.ToString ("yyyyMMddTHHmmss")).binlog</_Binlog>
     </PropertyGroup>
     <Exec
         Condition=" '$(HostOS)' != 'Windows' "

src/Mono.Android/javadoc-copyright.xml

@@ -1,5 +1 @@
-<para>Portions of this page are modifications based on work created and shared by the <format type="text/html">
-<a href="https://developers.google.com/terms/site-policies" title="Android Open Source Project">Android Open Source Project</a>
-</format> and used according to terms described in the <format type="text/html">
-<a href="https://creativecommons.org/licenses/by/2.5/" title="Creative Commons 2.5 Attribution License">Creative Commons 2.5 Attribution License.</a></format>
-</para>
+<para>Portions of this page are modifications based on work created and shared by the <format type="text/html"><a href="https://developers.google.com/terms/site-policies" title="Android Open Source Project">Android Open Source Project</a></format> and used according to terms described in the <format type="text/html"><a href="https://creativecommons.org/licenses/by/2.5/" title="Creative Commons 2.5 Attribution License">Creative Commons 2.5 Attribution License.</a></format></para>