Skip to content

Commit ffc3aeb

Browse files
jonthyselljonthysell
committed
Updated Native API docs with new UpdateNativeApiDocs.ps1 script
1 parent af2c1c2 commit ffc3aeb

File tree

243 files changed

+4750
-1333
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

243 files changed

+4750
-1333
lines changed

‎.github/scripts/UpdateNativeApiDocs.ps1‎

Lines changed: 209 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,209 @@
1+
#
2+
# UpdateNativeApiDocs.ps1 is a PowerShell script designed to download the
3+
# API docs from the specified RNW CI build in ADO and integrate them into
4+
# our docs folder, properly tagged with New/Old architecture tags
5+
6+
param(
7+
[Parameter(Mandatory=$true)]
8+
[int]$BuildId,
9+
[boolean]$Clean = $True
10+
)
11+
12+
Function Download-BuildArtifact([int]$BuildId, [string] $ArtifactName, [string]$DestPath = $env:TEMP)
13+
{
14+
Write-Host "Downloading `"$ArtifactName`" from build $BuildId"
15+
[string]$ArtifactUrl = "https://dev.azure.com/ms/8d8e50dd-c5b4-4b44-8668-86558c5aa5b7/_apis/build/builds/$BuildId/artifacts?artifactName=$ArtifactName&api-version=7.1&%24format=zip"
16+
[string]$ArtifactZipFile = Join-Path $DestPath "$ArtifactName.zip"
17+
18+
Write-Debug "Downloading `"$ArtifactUrl`""
19+
Invoke-WebRequest $ArtifactUrl -OutFile $ArtifactZipFile
20+
21+
Write-Debug "Extracting `"$ArtifactZipFile`""
22+
Expand-Archive -LiteralPath $ArtifactZipFile -DestinationPath $DestPath -Force
23+
24+
[string]$ExtractedPath = Join-Path $DestPath $ArtifactName
25+
26+
Write-Debug "Artifact extracted to `"$ExtractedPath`""
27+
return $ExtractedPath
28+
}
29+
30+
Function Create-WinRtApiDocWithBadge([string]$SourceDocPath, [string]$DestDocPath, [string]$BadgeMd)
31+
{
32+
Write-Host "Creating `"$DestDocPath`""
33+
34+
# Load content
35+
$Content = (Get-Content $SourceDocPath -Raw)
36+
37+
# Add Badge
38+
$Content = $Content -replace "---\r\n\r\n", "---`r`n`r`n$($BadgeMd)`r`n`r`n"
39+
40+
# Clean up spacing
41+
$Content = $Content -replace "(\r\n){3,}", "`r`n`r`n"
42+
43+
# Fix links
44+
$Content = $Content -replace "https://docs.microsoft.com/uwp/api/Windows.UI.Xaml", "https://learn.microsoft.com/uwp/api/Windows.UI.Xaml" # Workaround for https://github.com/asklar/winmd2md/issues/8
45+
$Content = $Content -replace "https://docs.microsoft.com/uwp/api/Microsoft.UI", "https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/Microsoft.UI" # Workaround for https://github.com/asklar/winmd2md/issues/7
46+
$Content = $Content -replace "https://docs.microsoft.com/uwp/api/Microsoft.ReactNative\.(\w+\.)*(\w+)", '$2' # Workaround for https://github.com/asklar/winmd2md/issues/9
47+
48+
$Content = $Content.Trim()
49+
50+
# Write final file
51+
$Content | Out-File -Encoding utf8NoBOM $DestDocPath
52+
}
53+
54+
Function Get-DocKind([string]$DocPath) {
55+
[string]$Kind = "unknown"
56+
$KindMatches = ((Get-Content $DocPath -Raw) | Select-String -Pattern 'Kind: `(\w+)`').Matches
57+
if (($KindMatches.Length -gt 0) -and ($KindMatches[0].Groups.Length -gt 1)) {
58+
$Kind = $KindMatches[0].Groups[1]
59+
}
60+
return $Kind
61+
}
62+
63+
Function Merge-WinRtApiDocs([string]$OldArchDocsPath, [string]$NewArchDocsPath, [string]$OutputDocsPath)
64+
{
65+
Write-Host "Merging WinRT API docs"
66+
67+
[string]$NewAndOldArchBadgeMd = "![Architecture](https://img.shields.io/badge/architecture-new_&_old-green)"
68+
[string]$NewArchOnlyBadgeMd = "![Architecture](https://img.shields.io/badge/architecture-new_only-blue)"
69+
[string]$OldArchOnlyBadgeMd = "![Architecture](https://img.shields.io/badge/architecture-old_only-yellow)"
70+
71+
$OldArchFiles = Get-ChildItem -Path $OldArchDocsPath -File -Filter *.md
72+
$NewArchFiles = Get-ChildItem -Path $NewArchDocsPath -File -Filter *.md
73+
74+
$AllFilesSet = New-Object System.Collections.Generic.HashSet[string];
75+
$($OldArchFiles; $NewArchFiles) | ForEach-Object { $AllFilesSet.Add($_.Name) | Out-Null }
76+
77+
$AllTypesByKind = @{}
78+
79+
# Find and process docs that are Old Arch Only
80+
Compare-Object $OldArchFiles $NewArchFiles -Property Name | Where-Object { $_.SideIndicator -eq "<=" } |
81+
ForEach-Object {
82+
Write-Debug "Old Arch Only: $($_.Name)"
83+
Create-WinRtApiDocWithBadge -SourceDocPath (Join-Path $OldArchDocsPath $_.Name) -DestDocPath (Join-Path $OutputDocsPath $_.Name) -BadgeMd $OldArchOnlyBadgeMd
84+
if ($AllFilesSet.Remove($_.Name)) {
85+
$Kind = Get-DocKind -DocPath (Join-Path $OutputDocsPath $_.Name)
86+
if ($AllTypesByKind[$Kind] -eq $Null) { $AllTypesByKind[$Kind] = @() }
87+
$AllTypesByKind[$Kind] += $_.Name.Replace("-api-windows.md", "")
88+
}
89+
}
90+
91+
# Find and process docs that are New Arch Only
92+
Compare-Object $NewArchFiles $OldArchFiles -Property Name | Where-Object { $_.SideIndicator -eq "<=" } |
93+
ForEach-Object {
94+
Write-Debug "New Arch Only: $($_.Name)"
95+
Create-WinRtApiDocWithBadge -SourceDocPath (Join-Path $NewArchDocsPath $_.Name) -DestDocPath (Join-Path $OutputDocsPath $_.Name) -BadgeMd $NewArchOnlyBadgeMd
96+
if ($AllFilesSet.Remove($_.Name)) {
97+
$Kind = Get-DocKind -DocPath (Join-Path $OutputDocsPath $_.Name)
98+
if ($AllTypesByKind[$Kind] -eq $Null) { $AllTypesByKind[$Kind] = @() }
99+
$AllTypesByKind[$Kind] += $_.Name.Replace("-api-windows.md", "")
100+
}
101+
}
102+
103+
# Process remaining docs are both Old and New Arch
104+
$AllFilesSet |
105+
ForEach-Object {
106+
Write-Debug "Old&New Arch: $_"
107+
$OldContent = (Get-Content (Join-Path $OldArchDocsPath $_) -Raw)
108+
$NewContent = (Get-Content (Join-Path $NewArchDocsPath $_) -Raw)
109+
if ($OldContent -eq $NewContent)
110+
{
111+
Write-Debug "Same Content: $_"
112+
Create-WinRtApiDocWithBadge -SourceDocPath (Join-Path $OldArchDocsPath $_) -DestDocPath (Join-Path $OutputDocsPath $_) -BadgeMd $NewAndOldArchBadgeMd
113+
}
114+
else
115+
{
116+
Write-Debug "Diff Content: $_"
117+
$MergedFilePath = (Join-Path $DownloadPath $_)
118+
119+
$NewContent = $NewContent -replace "---\r\n\r\n", "---`r`n`r`n# New Architecture`r`n`r`n"
120+
$NewContent = $NewContent -replace "\r\n#", "`r`n##"
121+
122+
$OldContent = $OldContent -replace "---(.*\r\n){1,}---\r\n\r\n", "`r`n`r`n# Old Architecture`r`n`r`n"
123+
$OldContent = $OldContent -replace "\r\n#", "`r`n##"
124+
125+
($NewContent + $OldContent) | Out-File -Encoding utf8NoBOM -NoNewline $MergedFilePath
126+
Create-WinRtApiDocWithBadge -SourceDocPath $MergedFilePath -DestDocPath (Join-Path $OutputDocsPath $_) -BadgeMd $NewAndOldArchBadgeMd
127+
}
128+
$Kind = Get-DocKind -DocPath (Join-Path $OutputDocsPath $_)
129+
if ($AllTypesByKind[$Kind] -eq $Null) { $AllTypesByKind[$Kind] = @() }
130+
$AllTypesByKind[$Kind] += $_.Replace("-api-windows.md", "")
131+
}
132+
133+
# Clean up links to enum type values (workaround for https://github.com/asklar/winmd2md/issues/10)
134+
(Get-ChildItem -Path $OutputDocsPath -File -Filter *-api-windows.md) | ForEach-Object {
135+
$FilePath = $_
136+
$FileContent = (Get-Content $FilePath -Raw)
137+
$AllTypesByKind['enum'] | ForEach-Object {
138+
$FileContent = $FileContent -replace "\($_#\w+\)", "($_)"
139+
}
140+
$FileContent | Out-File -Encoding utf8NoBOM -NoNewLine $FilePath
141+
}
142+
143+
# Recreate index (workaround for https://github.com/asklar/winmd2md/issues/10)
144+
[string]$IndexContent = ""
145+
$IndexContent += "---`r`n"
146+
$IndexContent += "id: Native-API-Reference`r`n"
147+
$IndexContent += "title: namespace Microsoft.ReactNative`r`n"
148+
$IndexContent += "sidebar_label: Full reference`r`n"
149+
$IndexContent += "---`r`n"
150+
$IndexContent += "`r`n"
151+
$IndexContent += $NewAndOldArchBadgeMd + "`r`n"
152+
$IndexContent += "`r`n"
153+
154+
$AllTypesByKind.Keys | Where-Object { $_ -ne 'unknown' } | Sort-Object | ForEach-Object {
155+
$IndexContent += "## $($_.Substring(0,1).ToUpper())$($_.Substring(1))$($_.EndsWith("s") ? "es" : "s")`r`n"
156+
$AllTypesByKind[$_] | Sort-Object | ForEach-Object {
157+
$IndexContent += "- [$_]($_)`r`n"
158+
}
159+
$IndexContent += "`r`n"
160+
}
161+
162+
$IndexContent = $IndexContent.Trim()
163+
164+
$IndexPath = (Join-Path $OutputDocsPath "index-api-windows.md")
165+
166+
Write-Host "Creating `"$IndexPath`""
167+
$IndexContent | Out-File -Encoding utf8NoBOM $IndexPath
168+
}
169+
170+
[string] $RepoRoot = Resolve-Path "$PSScriptRoot/../.."
171+
172+
$StartingLocation = Get-Location
173+
Set-Location -Path $RepoRoot
174+
175+
try
176+
{
177+
Write-Host "UpdateNativeApiDocs -BuildId $BuildId"
178+
179+
$DownloadPath = Join-Path $env:TEMP "UpdateNativeApiDocs-$BuildId"
180+
Write-Debug "Downloading artifacts to `"$DownloadPath`""
181+
if (Test-Path $DownloadPath)
182+
{
183+
Write-Debug "Deleting existing `"$DownloadPath`""
184+
Remove-Item -Path $DownloadPath -Recurse -Force
185+
}
186+
187+
Write-Debug "Creating new `"$DownloadPath`""
188+
New-Item $DownloadPath -ItemType "Directory" | Out-Null
189+
190+
Write-Debug "Downloading WinRT API docs from $BuildId"
191+
[string]$OldArchDocsPath = Download-BuildArtifact -BuildId $BuildId -ArtifactName "WinRT Api docs - Universal Build X64Debug-1" -DestPath $DownloadPath
192+
[string]$NewArchDocsPath = Download-BuildArtifact -BuildId $BuildId -ArtifactName "WinRT Api docs - Universal Build X64DebugFabric-1" -DestPath $DownloadPath
193+
194+
[string]$OutputDocsPath = Join-Path $RepoRoot "docs/native-api"
195+
196+
if ($Clean) {
197+
Write-Debug "Cleaning `"$OutputDocsPath`""
198+
Remove-Item -Path $OutputDocsPath -Recurse -Force
199+
New-Item $OutputDocsPath -ItemType "Directory" | Out-Null
200+
}
201+
202+
Merge-WinRtApiDocs -OldArchDocsPath $OldArchDocsPath -NewArchDocsPath $NewArchDocsPath -OutputDocsPath $OutputDocsPath
203+
}
204+
finally
205+
{
206+
Set-Location -Path $StartingLocation
207+
}
208+
209+
exit 0

‎docs/native-api/AccessibilityAction-api-windows.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,8 @@ id: AccessibilityAction
33
title: AccessibilityAction
44
---
55

6+
![Architecture](https://img.shields.io/badge/architecture-old_only-yellow)
7+
68
Kind: `struct`
79

810
## Fields
@@ -12,7 +14,5 @@ Type: `string`
1214
### Name
1315
Type: `string`
1416

15-
16-
1717
## Referenced by
1818
- [`AccessibilityActionEventHandler`](AccessibilityActionEventHandler)

‎docs/native-api/AccessibilityActionEventHandler-api-windows.md‎

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -3,14 +3,12 @@ id: AccessibilityActionEventHandler
33
title: AccessibilityActionEventHandler
44
---
55

6+
![Architecture](https://img.shields.io/badge/architecture-old_only-yellow)
7+
68
Kind: `delegate`
79

810
## Invoke
911
void **`Invoke`**([`AccessibilityAction`](AccessibilityAction) action)
1012

11-
12-
13-
14-
1513
## Referenced by
1614
- [`DynamicAutomationProperties`](DynamicAutomationProperties)

‎docs/native-api/AccessibilityInvokeEventHandler-api-windows.md‎

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -3,14 +3,12 @@ id: AccessibilityInvokeEventHandler
33
title: AccessibilityInvokeEventHandler
44
---
55

6+
![Architecture](https://img.shields.io/badge/architecture-old_only-yellow)
7+
68
Kind: `delegate`
79

810
## Invoke
911
void **`Invoke`**()
1012

11-
12-
13-
14-
1513
## Referenced by
1614
- [`DynamicAutomationProperties`](DynamicAutomationProperties)

‎docs/native-api/AccessibilityRoles-api-windows.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,8 @@ id: AccessibilityRoles
33
title: AccessibilityRoles
44
---
55

6+
![Architecture](https://img.shields.io/badge/architecture-old_only-yellow)
7+
68
Kind: `enum`
79

810
| Name | Value | Description |
@@ -40,6 +42,5 @@ Kind: `enum`
4042
|`Unknown` | 0x1e | |
4143
|`CountRoles` | 0x1f | |
4244

43-
4445
## Referenced by
4546
- [`DynamicAutomationProperties`](DynamicAutomationProperties)

‎docs/native-api/AccessibilityStateCheckedValue-api-windows.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,8 @@ id: AccessibilityStateCheckedValue
33
title: AccessibilityStateCheckedValue
44
---
55

6+
![Architecture](https://img.shields.io/badge/architecture-old_only-yellow)
7+
68
Kind: `enum`
79

810
| Name | Value | Description |
@@ -11,6 +13,5 @@ Kind: `enum`
1113
|`Checked` | 0x1 | |
1214
|`Mixed` | 0x2 | |
1315

14-
1516
## Referenced by
1617
- [`DynamicAutomationProperties`](DynamicAutomationProperties)

‎docs/native-api/AccessibilityStates-api-windows.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,8 @@ id: AccessibilityStates
33
title: AccessibilityStates
44
---
55

6+
![Architecture](https://img.shields.io/badge/architecture-old_only-yellow)
7+
68
Kind: `enum`
79

810
| Name | Value | Description |

‎docs/native-api/AccessibilityValue-api-windows.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,8 @@ id: AccessibilityValue
33
title: AccessibilityValue
44
---
55

6+
![Architecture](https://img.shields.io/badge/architecture-old_only-yellow)
7+
68
Kind: `enum`
79

810
| Name | Value | Description |

‎docs/native-api/ActivityIndicatorComponentView-api-windows.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
---
2+
id: ActivityIndicatorComponentView
3+
title: ActivityIndicatorComponentView
4+
---
5+
6+
![Architecture](https://img.shields.io/badge/architecture-new_only-blue)
7+
8+
Kind: `class`
9+
10+
Extends: [`ViewComponentView`](ViewComponentView)
11+
12+
> **EXPERIMENTAL**

‎docs/native-api/AnimationClass-api-windows.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
---
2+
id: AnimationClass
3+
title: AnimationClass
4+
---
5+
6+
![Architecture](https://img.shields.io/badge/architecture-new_only-blue)
7+
8+
Kind: `enum`
9+
10+
| Name | Value | Description |
11+
|--|--|--|
12+
|`None` | 0x0 | |
13+
|`ScrollBar` | 0x1 | |
14+
|`ScrollBarThumbHorizontal` | 0x2 | |
15+
|`ScrollBarThumbVertical` | 0x3 | |
16+
|`SwitchThumb` | 0x4 | |
17+
18+
## Referenced by
19+
- [`IVisual`](IVisual)

0 commit comments

Comments
 (0)