Skip to content

Commit 3d2ae4b

Browse files
pjcollinspjcollins
authored
[Mono.Android] Generate API docs for API level 35 (#9647)
Changes: dotnet/java-interop@2c06b3c...fe00cef * dotnet/java-interop@fe00cef5: [Java.Interop.Tools.JavaSource] Support html tags with attributes (dotnet/java-interop#1286) Bump to dotnet/java-interop@fe00cef5 to get Javadoc import fixes. Updates xaprepare and Mono.Android to generate API Docs against API-35 sources. The `azure-pipelines-apidocs.yaml` pipeline has been updated to use the 1ES pipeline template to improve compatibility with existing yaml templates. The semi-automated API docs build and update workflow uses the .NET Framework version of Mdoc and the `RunMdoc` target has been updated to continue to mirror that workflow.
1 parent 6af0a5d commit 3d2ae4b

File tree

4 files changed

+143
-124
lines changed

4 files changed

+143
-124
lines changed

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

+132-113
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,13 @@
88
trigger: none
99
pr: none
1010

11+
resources:
12+
repositories:
13+
- repository: 1esPipelines
14+
type: git
15+
name: 1ESPipelineTemplates/1ESPipelineTemplates
16+
ref: refs/tags/release
17+
1118
parameters:
1219
- name: apiLevel
1320
displayName: AndroidApiLevel property value
@@ -50,118 +57,130 @@ variables:
5057
value: ''
5158

5259

53-
stages:
54-
- stage: mac_build
55-
displayName: Build
56-
dependsOn: []
57-
jobs:
58-
- job: mac_build_update_docs
59-
displayName: Update API Docs
60-
pool:
61-
name: $(SharedMacPool)
62-
demands:
63-
- macOS.Name -equals $(SharedMacName)
64-
- Agent.OSArchitecture -equals $(SharedMacArch)
65-
timeoutInMinutes: 120
66-
workspace:
67-
clean: all
68-
steps:
69-
- checkout: self
70-
submodules: recursive
71-
72-
- script: echo "##vso[task.setvariable variable=JI_JAVA_HOME]$HOME/android-toolchain/jdk-17"
73-
displayName: set JI_JAVA_HOME
74-
75-
# Set MSBuild property overrides if parameters are set
76-
- ${{ if ne(parameters.apiLevel, 'default') }}:
77-
- script: echo "##vso[task.setvariable variable=DocsApiLevelArg]-p:DocsApiLevel=${{ parameters.apiLevel }}"
78-
displayName: set DocsApiLevelArg
79-
80-
- ${{ if ne(parameters.platformId, 'default') }}:
81-
- script: echo "##vso[task.setvariable variable=DocsPlatformIdArg]-p:DocsPlatformId=${{ parameters.platformId }}"
82-
displayName: set DocsPlatformIdArg
83-
84-
- ${{ if ne(parameters.frameworkVersion, 'default') }}:
85-
- script: echo "##vso[task.setvariable variable=DocsFxVersionArg]-p:DocsFxVersion=${{ parameters.frameworkVersion }}"
86-
displayName: set DocsFxVersionArg
87-
88-
- ${{ if ne(parameters.mdocVersion, 'default') }}:
89-
- script: echo "##vso[task.setvariable variable=MdocPackageVersionArg]-p:MdocPackageVersion=${{ parameters.mdocVersion }}"
90-
displayName: set MdocPackageVersionArg
91-
92-
- ${{ if ne(parameters.javadocVerbosity, 'default') }}:
93-
- script: echo "##vso[task.setvariable variable=AndroidJavadocVerbosity]-p:AndroidJavadocVerbosity=${{ parameters.javadocVerbosity }}"
94-
displayName: set AndroidJavadocVerbosity
95-
96-
- template: yaml-templates/use-dot-net.yaml
97-
98-
- task: NuGetAuthenticate@1
99-
displayName: authenticate with azure artifacts
100-
inputs:
101-
forceReinstallCredentialProvider: true
102-
103-
- template: yaml-templates/run-xaprepare.yaml
104-
parameters:
105-
displayName: update mono
106-
arguments: --s=UpdateMono
107-
108-
- script: make prepare CONFIGURATION=$(XA.Build.Configuration) PREPARE_CI=1 PREPARE_AUTOPROVISION=1
109-
workingDirectory: $(Build.SourcesDirectory)
110-
displayName: make prepare
111-
112-
- script: >-
113-
make update-api-docs CONFIGURATION=$(XA.Build.Configuration)
114-
MSBUILD_ARGS='$(DocsApiLevelArg) $(DocsPlatformIdArg) $(DocsFxVersionArg) $(MdocPackageVersionArg) $(AndroidJavadocVerbosity)'
115-
workingDirectory: $(Build.SourcesDirectory)
116-
displayName: make update-api-docs
117-
118-
- script: >
119-
mkdir -p $(Build.StagingDirectory)/docs-binaries &&
120-
ln $(Build.SourcesDirectory)/bin/$(XA.Build.Configuration)/lib/xamarin.android/xbuild-frameworks/Microsoft.Android/34/*.dll $(Build.StagingDirectory)/docs-binaries/ &&
121-
ln $(Build.SourcesDirectory)/bin/$(XA.Build.Configuration)/lib/xamarin.android/xbuild-frameworks/Microsoft.Android/34/*.xml $(Build.StagingDirectory)/docs-binaries/
122-
displayName: copy docs files
123-
124-
- task: PublishPipelineArtifact@1
125-
displayName: upload docs files
126-
inputs:
127-
artifactName: Binaries
128-
targetPath: $(Build.StagingDirectory)/docs-binaries
129-
130-
- script: >
131-
mkdir -p $(Build.StagingDirectory)/api-doc-diff &&
132-
ln $(Build.SourcesDirectory)/bin/Build$(XA.Build.Configuration)/UpdateApiDocs*.diff $(Build.StagingDirectory)/api-doc-diff/
133-
displayName: copy api docs diff
134-
135-
- task: PublishPipelineArtifact@1
136-
displayName: upload api docs diff
137-
inputs:
138-
artifactName: Api Docs Diff
139-
targetPath: $(Build.StagingDirectory)/api-doc-diff
140-
141-
- template: yaml-templates/upload-results.yaml
142-
parameters:
143-
artifactName: Build Results - API Docs Update
144-
includeBuildResults: true
145-
condition: always()
146-
147-
- powershell: |
148-
$docsUpdateBinlog = Get-ChildItem -Path "$(Build.SourcesDirectory)/bin/Build$(XA.Build.Configuration)" -Filter *UpdateApiDocs-*.binlog | Select-Object -First 1
149-
$buildLog = "$(Build.SourcesDirectory)/bin/Build$(XA.Build.Configuration)/temp-build.log"
150-
& "$(Build.SourcesDirectory)/bin/$(XA.Build.Configuration)/dotnet/dotnet" build $docsUpdateBinlog > $buildLog
151-
152-
$issueContent = & {
153-
Get-Content -Path $buildLog | Select-String "## Exception translating remarks"
154-
Get-Content -Path $buildLog | Select-String "## Unable to translate remarks"
155-
Get-Content -Path $buildLog | Select-String "JavadocImport-"
156-
}
157-
158-
if ($issueContent) {
159-
Write-Host "The following issues were found, review the build log for more details:"
160-
Write-Host ""
161-
foreach ($line in $issueContent) {
162-
Write-Host $line
60+
extends:
61+
${{ if ne(variables['Build.Reason'], 'PullRequest') }}:
62+
template: v1/1ES.Official.PipelineTemplate.yml@1esPipelines
63+
${{ else }}:
64+
template: v1/1ES.Unofficial.PipelineTemplate.yml@1esPipelines
65+
parameters:
66+
sdl:
67+
sourceAnalysisPool:
68+
name: AzurePipelines-EO
69+
image: $(WindowsPoolImage1ESPT)
70+
os: windows
71+
suppression:
72+
suppressionFile: $(Build.SourcesDirectory)\.gdn\.gdnsuppress
73+
stages:
74+
- stage: mac_build
75+
displayName: Build
76+
dependsOn: []
77+
jobs:
78+
- job: mac_build_update_docs
79+
displayName: Update API Docs
80+
pool:
81+
name: $(SharedMacPool)
82+
demands:
83+
- macOS.Name -equals $(SharedMacName)
84+
- Agent.OSArchitecture -equals $(SharedMacArch)
85+
os: macOS
86+
timeoutInMinutes: 120
87+
workspace:
88+
clean: all
89+
templateContext:
90+
outputs:
91+
- output: pipelineArtifact
92+
displayName: upload docs binaries
93+
artifactName: Binaries
94+
targetPath: $(Build.SourcesDirectory)/src/Mono.Android/obj/docs-gen-temp
95+
- output: pipelineArtifact
96+
displayName: upload docs diff
97+
artifactName: Api Docs Diff
98+
targetPath: $(Build.StagingDirectory)/api-doc-diff
99+
steps:
100+
- checkout: self
101+
submodules: recursive
102+
103+
- script: |
104+
echo "##vso[task.setvariable variable=JI_JAVA_HOME]$HOME/android-toolchain/jdk-17"
105+
echo "##vso[task.setvariable variable=JAVA_HOME]$HOME/android-toolchain/jdk-17"
106+
displayName: set JI_JAVA_HOME
107+
108+
# Set MSBuild property overrides if parameters are set
109+
- ${{ if ne(parameters.apiLevel, 'default') }}:
110+
- script: echo "##vso[task.setvariable variable=DocsApiLevelArg]-p:DocsApiLevel=${{ parameters.apiLevel }}"
111+
displayName: set DocsApiLevelArg
112+
113+
- ${{ if ne(parameters.platformId, 'default') }}:
114+
- script: echo "##vso[task.setvariable variable=DocsPlatformIdArg]-p:DocsPlatformId=${{ parameters.platformId }}"
115+
displayName: set DocsPlatformIdArg
116+
117+
- ${{ if ne(parameters.frameworkVersion, 'default') }}:
118+
- script: echo "##vso[task.setvariable variable=DocsFxVersionArg]-p:DocsFxVersion=${{ parameters.frameworkVersion }}"
119+
displayName: set DocsFxVersionArg
120+
121+
- ${{ if ne(parameters.mdocVersion, 'default') }}:
122+
- script: echo "##vso[task.setvariable variable=MdocPackageVersionArg]-p:MdocPackageVersion=${{ parameters.mdocVersion }}"
123+
displayName: set MdocPackageVersionArg
124+
125+
- ${{ if ne(parameters.javadocVerbosity, 'default') }}:
126+
- script: echo "##vso[task.setvariable variable=AndroidJavadocVerbosity]-p:AndroidJavadocVerbosity=${{ parameters.javadocVerbosity }}"
127+
displayName: set AndroidJavadocVerbosity
128+
129+
- template: /build-tools/automation/yaml-templates/use-dot-net.yaml@self
130+
131+
- task: NuGetAuthenticate@1
132+
displayName: authenticate with azure artifacts
133+
inputs:
134+
forceReinstallCredentialProvider: true
135+
136+
- script: dotnet tool update -v:n boots --version 1.1.0.36 --add-source "https://api.nuget.org/v3/index.json" --global
137+
displayName: Install boots
138+
139+
- script: boots https://download.mono-project.com/archive/6.12.0/macos-10-universal/MonoFramework-MDK-6.12.0.188.macos10.xamarin.universal.pkg
140+
displayName: Install Mono
141+
142+
- script: make prepare CONFIGURATION=$(XA.Build.Configuration) PREPARE_CI=1 PREPARE_AUTOPROVISION=1
143+
workingDirectory: $(Build.SourcesDirectory)
144+
displayName: make prepare
145+
146+
- script: >-
147+
make update-api-docs CONFIGURATION=$(XA.Build.Configuration)
148+
MSBUILD_ARGS='$(DocsApiLevelArg) $(DocsPlatformIdArg) $(DocsFxVersionArg) $(MdocPackageVersionArg) $(AndroidJavadocVerbosity)'
149+
workingDirectory: $(Build.SourcesDirectory)
150+
displayName: make update-api-docs
151+
152+
- script: >
153+
mkdir -p $(Build.StagingDirectory)/api-doc-diff &&
154+
ln $(Build.SourcesDirectory)/bin/Build$(XA.Build.Configuration)/UpdateApiDocs*.diff $(Build.StagingDirectory)/api-doc-diff/ &&
155+
ln $(Build.SourcesDirectory)/external/android-api-docs/docs/xml/index.xml $(Build.StagingDirectory)/api-doc-diff/
156+
displayName: copy api docs diff
157+
158+
- template: /build-tools/automation/yaml-templates/upload-results.yaml@self
159+
parameters:
160+
artifactName: Build Results - API Docs Update
161+
includeBuildResults: true
162+
condition: always()
163+
164+
- powershell: |
165+
$docsUpdateBinlog = Get-ChildItem -Path "$(Build.SourcesDirectory)/bin/Build$(XA.Build.Configuration)" -Filter *UpdateApiDocs-*.binlog | Select-Object -First 1
166+
$buildLog = "$(Build.SourcesDirectory)/bin/Build$(XA.Build.Configuration)/temp-UpdateApiDocs-build.log"
167+
& "$(Build.SourcesDirectory)/bin/$(XA.Build.Configuration)/dotnet/dotnet" build $docsUpdateBinlog > $buildLog
168+
169+
$issueContent = & {
170+
Get-Content -Path $buildLog | Select-String "## Exception translating remarks" -Context 0, 3
171+
Get-Content -Path $buildLog | Select-String "## Unable to translate remarks" -Context 0, 3
172+
Get-Content -Path $buildLog | Select-String "JavadocImport-" -Context 0, 3
173+
}
174+
175+
if ($issueContent) {
176+
Write-Host "The following issues were found, review the build log for more details:"
163177
Write-Host ""
178+
foreach ($line in $issueContent) {
179+
Write-Host $line
180+
Write-Host ""
181+
}
182+
exit 1
164183
}
165-
exit 1
166-
}
167-
displayName: Report issues in docs generation
184+
Write-Host "No issues found."
185+
displayName: Report issues in docs generation
186+
continueOnError: true

‎build-tools/xaprepare/xaprepare/ConfigAndData/Dependencies/AndroidToolchain.cs

+3-3
Original file line numberDiff line numberDiff line change
@@ -75,11 +75,11 @@ public AndroidToolchain ()
7575
new AndroidPlatformComponent ("platform-35_r01", apiLevel: "35", pkgRevision: "1", isLatestStable: true),
7676
new AndroidPlatformComponent ("platform-Baklava_r03", apiLevel: "Baklava", pkgRevision: "3", isLatestStable: true),
7777

78-
new AndroidToolchainComponent ("sources-34_r01",
79-
destDir: Path.Combine ("sources", "android-34"),
78+
new AndroidToolchainComponent ("source-35_r01",
79+
destDir: Path.Combine ("sources", "android-35"),
8080
pkgRevision: "1",
8181
dependencyType: AndroidToolchainComponentType.BuildDependency,
82-
buildToolVersion: "34.1"
82+
buildToolVersion: "35.1"
8383
),
8484
new AndroidToolchainComponent ("docs-24_r01",
8585
destDir: "docs",

‎external/Java.Interop

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

+7-7
Original file line numberDiff line numberDiff line change
@@ -238,12 +238,15 @@
238238

239239
<PropertyGroup>
240240
<!-- Override these properties to generate docs against a specific API level -->
241-
<DocsApiLevel Condition=" '$(DocsApiLevel)' == '' ">34</DocsApiLevel>
241+
<DocsApiLevel Condition=" '$(DocsApiLevel)' == '' ">35</DocsApiLevel>
242242
<DocsPlatformId Condition=" '$(DocsPlatformId)' == '' ">$(DocsApiLevel)</DocsPlatformId>
243243
<DocsFxMoniker Condition=" '$(DocsFxMoniker)' == '' ">net-android-$(DocsApiLevel).0</DocsFxMoniker>
244244
<DocsExportOutput Condition=" '$(DocsExportOutput)' == '' ">$(_MonoAndroidNETDefaultOutDir)Mono.Android.xml</DocsExportOutput>
245245
<_ExternalDocsRoot>$(XamarinAndroidSourcePath)external/android-api-docs/docs/xml</_ExternalDocsRoot>
246246
<_LogPrefix>$(MSBuildThisFileDirectory)../../bin/Build$(Configuration)/UpdateApiDocs-$([System.DateTime]::Now.ToString ("yyyyMMddTHHmmss"))</_LogPrefix>
247+
<_ManagedRuntime Condition=" !$([MSBuild]::IsOSPlatform('windows')) ">mono</_ManagedRuntime>
248+
<_MdocExe Condition=" '$(Pkgmdoc)' != '' ">"$(Pkgmdoc)/tools/net471/mdoc.exe"</_MdocExe>
249+
<_MdocExe Condition=" '$(Pkgmdoc)' == '' ">"$(XAPackagesDir)/mdoc/$(MdocPackageVersion)/tools/net471/mdoc.exe"</_MdocExe>
247250
<_Mdoc Condition=" '$(Pkgmdoc)' != '' ">"$(Pkgmdoc)/tools/net6.0/mdoc.dll"</_Mdoc>
248251
<_Mdoc Condition=" '$(Pkgmdoc)' == '' ">"$(XAPackagesDir)/mdoc/$(MdocPackageVersion)/tools/net6.0/mdoc.dll"</_Mdoc>
249252
</PropertyGroup>
@@ -270,6 +273,7 @@
270273
/>
271274
</Target>
272275

276+
<!-- `mdoc fx-bootstrap` and `mdoc update` require the .NET framework version of mdoc, a mono install will be needed to run the RunMdoc target on macOS/Linux -->
273277
<Target Name="RunMdoc">
274278
<MSBuild Projects="$(MSBuildThisFileDirectory)Mono.Android.csproj"
275279
Targets="_RunMdoc"
@@ -305,16 +309,12 @@
305309
SourceFiles="@(_FxAssembly);@(_FxAssemblyXml)"
306310
DestinationFolder="$(_RootFxDir)$(DocsFxMoniker)"
307311
/>
308-
<WriteLinesToFile
309-
File="$(_RootFxDir)frameworks.xml"
310-
Lines="$(FrameworksXmlContent)"
311-
/>
312312
<Exec
313-
Command="dotnet $(_Mdoc) fx-bootstrap -fx $(_RootFxDir) -importContent true"
313+
Command="$(_ManagedRuntime) $(_MdocExe) fx-bootstrap -fx $(_RootFxDir) -importContent true"
314314
WorkingDirectory="$(MSBuildThisFileDirectory)"
315315
/>
316316
<Exec
317-
Command="dotnet $(_Mdoc) update $(_Libdir) $(_Output) $(_DocTypeArgs) $(_FxConfig) $(_ExtraMdocArgs)"
317+
Command="$(_ManagedRuntime) $(_MdocExe) update $(_Libdir) $(_Output) $(_DocTypeArgs) $(_FxConfig) $(_ExtraMdocArgs)"
318318
WorkingDirectory="$(MSBuildThisFileDirectory)"
319319
/>
320320
</Target>

0 commit comments

Comments
 (0)