Skip to content

Commit bb2f920

Browse files
pjcollinspjcollins
committed
[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.
1 parent c59b591 commit bb2f920

File tree

3 files changed

+62
-30
lines changed

3 files changed

+62
-30
lines changed

‎Makefile‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -223,3 +223,6 @@ APK_SIZES_REFERENCE_DIR=tests/apk-sizes-reference
223223
update-apk-sizes-reference:
224224
-mkdir -p $(APK_SIZES_REFERENCE_DIR)
225225
cp -v *values-$(CONFIGURATION).csv $(APK_SIZES_REFERENCE_DIR)/
226+
227+
update-api-docs:
228+
$(call DOTNET_BINLOG,update-api-docs) -t:UpdateExternalDocumentation src/Mono.Android/Mono.Android.csproj

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

Lines changed: 29 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,22 @@
88
trigger: none
99
pr: none
1010

11+
parameters:
12+
- name: apiLevel
13+
displayName: AndroidApiLevel property value
14+
type: string
15+
default: 31
16+
17+
- name: platformId
18+
displayName: AndroidPlatformId property value
19+
type: string
20+
default: 31
21+
22+
- name: frameworkVersion
23+
displayName: AndroidFrameworkVersion property value
24+
type: string
25+
default: v12.0
26+
1127
# Global variables
1228
variables:
1329
- template: yaml-templates/variables.yaml
@@ -20,7 +36,8 @@ stages:
2036
- job: mac_build_update_docs
2137
displayName: Update API Docs
2238
pool:
23-
vmImage: macOS-11
39+
name: VSEng-Xamarin-RedmondMac-Android-Untrusted
40+
demands: macOS.Name -equals Monterey
2441
timeoutInMinutes: 120
2542
workspace:
2643
clean: all
@@ -47,28 +64,22 @@ stages:
4764
workingDirectory: $(Build.SourcesDirectory)
4865
displayName: make prepare
4966

50-
- task: MSBuild@1
51-
displayName: build jnienv-gen.csproj
52-
inputs:
53-
solution: $(Build.SourcesDirectory)/external/Java.Interop/build-tools/jnienv-gen/jnienv-gen.csproj
54-
configuration: $(XA.Build.Configuration)
55-
msbuildArguments: /restore
56-
57-
- task: MSBuild@1
58-
displayName: update android-api-docs
59-
inputs:
60-
solution: $(Build.SourcesDirectory)/src/Mono.Android/Mono.Android.csproj
61-
configuration: $(XA.Build.Configuration)
62-
msbuildArguments: /restore /t:UpdateExternalDocumentation
67+
- script: make update-api-docs CONFIGURATION=$(XA.Build.Configuration) MSBUILD_ARGS='-p:AndroidApiLevel=${{ parameters.apiLevel }} -p:AndroidPlatformId=${{ parameters.platformId }} -p:AndroidFrameworkVersion=${{ parameters.frameworkVersion }}'
68+
workingDirectory: $(Build.SourcesDirectory)
69+
displayName: make update-api-docs
6370

6471
- template: yaml-templates/upload-results.yaml
6572
parameters:
66-
xaSourcePath: $(System.DefaultWorkingDirectory)/xamarin-android
6773
artifactName: Build Results - API Docs Update
6874
includeBuildResults: true
6975

76+
- script: >
77+
mkdir -p $(Build.StagingDirectory)/api-doc-diff &&
78+
ln $(Build.SourcesDirectory)/bin/Build$(XA.Build.Configuration)/UpdateApiDocs*.diff $(Build.StagingDirectory)/api-doc-diff/
79+
displayName: copy api docs diff
80+
7081
- task: PublishPipelineArtifact@1
71-
displayName: upload Mono.Android docs
82+
displayName: upload api docs diff
7283
inputs:
73-
artifactName: Mono.Android Docs
74-
targetPath: $(Build.SourcesDirectory)/external/android-api-docs/docs/Mono.Android/en/
84+
artifactName: Api Docs Diff
85+
targetPath: $(Build.StagingDirectory)/api-doc-diff

‎src/Mono.Android/Mono.Android.targets‎

Lines changed: 30 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -75,14 +75,14 @@
7575
<!-- Pulls documentation from JavaDoc -->
7676
<PropertyGroup>
7777
<_JavaSourceUtilsJar>$(MicrosoftAndroidSdkOutDir)java-source-utils.jar</_JavaSourceUtilsJar>
78-
<_AndroidStableSrcDir>$(AndroidSdkDirectory)\platforms\android-$(AndroidLatestStableApiLevel)\src</_AndroidStableSrcDir>
78+
<_AndroidSrcDir>$(AndroidSdkDirectory)\platforms\android-$(AndroidApiLevel)\src</_AndroidSrcDir>
7979
<_AndroidJavadocXml>..\..\bin\Build$(Configuration)\android-javadoc.xml</_AndroidJavadocXml>
8080
</PropertyGroup>
8181

8282
<Target Name="_BuildAndroidJavadocXml"
8383
Condition=" '$(IncludeAndroidJavadoc)' == 'True' "
8484
BeforeTargets="CoreCompile"
85-
Inputs="$(MSBuildThisFile);$(_AndroidStableSrcDir)\source.properties;$(_JavaSourceUtilsJar)"
85+
Inputs="$(MSBuildThisFile);$(_AndroidSrcDir)\source.properties;$(_JavaSourceUtilsJar)"
8686
Outputs="$(_AndroidJavadocXml)">
8787
<ItemGroup>
8888
<_Doclink Include="--doc-copyright" />
@@ -95,11 +95,11 @@
9595
<_Doclink Include="https://developer.android.com/" />
9696
</ItemGroup>
9797
<ItemGroup>
98-
<_AndroidSources Include="$(_AndroidStableSrcDir)\android\**\*.java" />
99-
<_AndroidSources Include="$(_AndroidStableSrcDir)\java\**\*.java" />
100-
<_AndroidSources Include="$(_AndroidStableSrcDir)\javax\**\*.java" />
101-
<_AndroidSources Include="$(_AndroidStableSrcDir)\org\**\*.java" />
102-
<_AndroidSources Remove="$(_AndroidStableSrcDir)\**\*.annotated.java" />
98+
<_AndroidSources Include="$(_AndroidSrcDir)\android\**\*.java" />
99+
<_AndroidSources Include="$(_AndroidSrcDir)\java\**\*.java" />
100+
<_AndroidSources Include="$(_AndroidSrcDir)\javax\**\*.java" />
101+
<_AndroidSources Include="$(_AndroidSrcDir)\org\**\*.java" />
102+
<_AndroidSources Remove="$(_AndroidSrcDir)\**\*.annotated.java" />
103103
</ItemGroup>
104104
<PropertyGroup>
105105
<_Filenames>$(IntermediateOutputPath)\java-sources.txt</_Filenames>
@@ -111,7 +111,7 @@
111111
/>
112112
<ItemGroup>
113113
<_JSIArg Include="-v" />
114-
<_JSIArg Include="--source &quot;$(_AndroidStableSrcDir)&quot;" />
114+
<_JSIArg Include="--source &quot;$(_AndroidSrcDir)&quot;" />
115115
<_JSIArg Include="--output-javadoc &quot;$(_AndroidJavadocXml)&quot;" />
116116
<_JSIArg Include="@$(_Filenames)" />
117117
</ItemGroup>
@@ -289,16 +289,24 @@
289289
<Target Name="UpdateExternalDocumentation">
290290
<MSBuild Projects="$(MSBuildThisFileDirectory)Mono.Android.csproj"
291291
Properties="TargetFramework=monoandroid10"
292-
Targets="_UpdateExternalDocumentation;_RunMdoc"
292+
Targets="_UpdateExternalDocumentation;_RunMdoc;_GenerateApiDocsDiff"
293293
/>
294294
</Target>
295295
<Target Name="_UpdateExternalDocumentation">
296296
<RemoveDir Directories="$(BaseIntermediateOutputPath)" />
297297
<PropertyGroup>
298-
<_Binlog>$(MSBuildThisFileDirectory)../../bin/Build$(Configuration)/UpdateExternalDocumentation-$([System.DateTime]::Now.ToString ("yyyyMMddTHHmmss")).binlog</_Binlog>
298+
<_Binlog>$(MSBuildThisFileDirectory)../../bin/Build$(Configuration)/UpdateApiDocs-$([System.DateTime]::Now.ToString ("yyyyMMddTHHmmss")).binlog</_Binlog>
299299
</PropertyGroup>
300+
<ItemGroup>
301+
<_BuildProps Include="-p:IncludeAndroidJavadoc=True" />
302+
<_BuildProps Include="-p:TargetFramework=monoandroid10" />
303+
<!-- Override these properties to generate docs against a specific API level -->
304+
<_BuildProps Include="-p:AndroidApiLevel=$(AndroidApiLevel)" />
305+
<_BuildProps Include="-p:AndroidPlatformId=$(AndroidPlatformId)" />
306+
<_BuildProps Include="-p:AndroidFrameworkVersion=$(AndroidFrameworkVersion)" />
307+
</ItemGroup>
300308
<Exec
301-
Command="dotnet build -v:n -c $(Configuration) -p:IncludeAndroidJavadoc=True -bl:$(_Binlog)"
309+
Command="&quot;$(DotNetPreviewTool)&quot; build -v:n -c $(Configuration) -bl:$(_Binlog) @(_BuildProps, ' ')"
302310
IgnoreStandardErrorWarningFormat="True"
303311
WorkingDirectory="$(MSBuildThisFileDirectory)"
304312
/>
@@ -352,5 +360,15 @@
352360
WorkingDirectory="$(MSBuildThisFileDirectory)"
353361
/>
354362
</Target>
355-
363+
364+
<Target Name="_GenerateApiDocsDiff">
365+
<PropertyGroup>
366+
<_DiffFile>$(XamarinAndroidSourcePath)bin/Build$(Configuration)/UpdateApiDocs$([System.DateTime]::Now.ToString ("yyyyMMddTHHmmss")).diff</_DiffFile>
367+
</PropertyGroup>
368+
<Exec
369+
Command="git diff --output=&quot;$(_DiffFile)&quot;"
370+
WorkingDirectory="$(XamarinAndroidSourcePath)external/android-api-docs"
371+
/>
372+
</Target>
373+
356374
</Project>

0 commit comments

Comments
 (0)