Skip to content

Commit c50ea6e

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

File tree

253 files changed

+5045
-1361
lines changed

Some content is hidden

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

253 files changed

+5045
-1361
lines changed

‎.github/scripts/UpdateNativeApiDocs.ps1‎

Lines changed: 231 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,231 @@
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]$RepoRoot, [boolean]$Clean)
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+
[string]$OutputDocsPath = Join-Path $RepoRoot "docs/native-api"
80+
81+
if ($Clean) {
82+
Write-Debug "Cleaning `"$OutputDocsPath`""
83+
Remove-Item -Path $OutputDocsPath -Recurse -Force
84+
}
85+
New-Item $OutputDocsPath -ItemType "Directory" | Out-Null
86+
87+
# Find and process docs that are Old Arch Only
88+
Compare-Object $OldArchFiles $NewArchFiles -Property Name | Where-Object { $_.SideIndicator -eq "<=" } |
89+
ForEach-Object {
90+
Write-Debug "Old Arch Only: $($_.Name)"
91+
Create-WinRtApiDocWithBadge -SourceDocPath (Join-Path $OldArchDocsPath $_.Name) -DestDocPath (Join-Path $OutputDocsPath $_.Name) -BadgeMd $OldArchOnlyBadgeMd
92+
if ($AllFilesSet.Remove($_.Name)) {
93+
$Kind = Get-DocKind -DocPath (Join-Path $OutputDocsPath $_.Name)
94+
if ($AllTypesByKind[$Kind] -eq $Null) { $AllTypesByKind[$Kind] = @() }
95+
$AllTypesByKind[$Kind] += $_.Name.Replace("-api-windows.md", "")
96+
}
97+
}
98+
99+
# Find and process docs that are New Arch Only
100+
Compare-Object $NewArchFiles $OldArchFiles -Property Name | Where-Object { $_.SideIndicator -eq "<=" } |
101+
ForEach-Object {
102+
Write-Debug "New Arch Only: $($_.Name)"
103+
Create-WinRtApiDocWithBadge -SourceDocPath (Join-Path $NewArchDocsPath $_.Name) -DestDocPath (Join-Path $OutputDocsPath $_.Name) -BadgeMd $NewArchOnlyBadgeMd
104+
if ($AllFilesSet.Remove($_.Name)) {
105+
$Kind = Get-DocKind -DocPath (Join-Path $OutputDocsPath $_.Name)
106+
if ($AllTypesByKind[$Kind] -eq $Null) { $AllTypesByKind[$Kind] = @() }
107+
$AllTypesByKind[$Kind] += $_.Name.Replace("-api-windows.md", "")
108+
}
109+
}
110+
111+
# Process remaining docs are both Old and New Arch
112+
$AllFilesSet |
113+
ForEach-Object {
114+
Write-Debug "Old&New Arch: $_"
115+
$OldContent = (Get-Content (Join-Path $OldArchDocsPath $_) -Raw)
116+
$NewContent = (Get-Content (Join-Path $NewArchDocsPath $_) -Raw)
117+
if ($OldContent -eq $NewContent)
118+
{
119+
Write-Debug "Same Content: $_"
120+
Create-WinRtApiDocWithBadge -SourceDocPath (Join-Path $OldArchDocsPath $_) -DestDocPath (Join-Path $OutputDocsPath $_) -BadgeMd $NewAndOldArchBadgeMd
121+
}
122+
else
123+
{
124+
Write-Debug "Diff Content: $_"
125+
$MergedFilePath = (Join-Path $DownloadPath $_)
126+
127+
$NewContent = $NewContent -replace "---\r\n\r\n", "---`r`n`r`n# New Architecture`r`n`r`n"
128+
$NewContent = $NewContent -replace "\r\n#", "`r`n##"
129+
130+
$OldContent = $OldContent -replace "---(.*\r\n){1,}---\r\n\r\n", "`r`n`r`n# Old Architecture`r`n`r`n"
131+
$OldContent = $OldContent -replace "\r\n#", "`r`n##"
132+
133+
($NewContent + $OldContent) | Out-File -Encoding utf8NoBOM -NoNewline $MergedFilePath
134+
Create-WinRtApiDocWithBadge -SourceDocPath $MergedFilePath -DestDocPath (Join-Path $OutputDocsPath $_) -BadgeMd $NewAndOldArchBadgeMd
135+
}
136+
$Kind = Get-DocKind -DocPath (Join-Path $OutputDocsPath $_)
137+
if ($AllTypesByKind[$Kind] -eq $Null) { $AllTypesByKind[$Kind] = @() }
138+
$AllTypesByKind[$Kind] += $_.Replace("-api-windows.md", "")
139+
}
140+
141+
# Clean up links to enum type values (workaround for https://github.com/asklar/winmd2md/issues/10)
142+
(Get-ChildItem -Path $OutputDocsPath -File -Filter *-api-windows.md) | ForEach-Object {
143+
$FilePath = $_
144+
$FileContent = (Get-Content $FilePath -Raw)
145+
$AllTypesByKind['enum'] | ForEach-Object {
146+
$FileContent = $FileContent -replace "\($_#\w+\)", "($_)"
147+
}
148+
$FileContent | Out-File -Encoding utf8NoBOM -NoNewLine $FilePath
149+
}
150+
151+
# Recreate index (workaround for https://github.com/asklar/winmd2md/issues/10)
152+
[string]$IndexContent = ""
153+
$IndexContent += "---`r`n"
154+
$IndexContent += "id: Native-API-Reference`r`n"
155+
$IndexContent += "title: Microsoft.ReactNative APIs`r`n"
156+
$IndexContent += "---`r`n"
157+
$IndexContent += "`r`n"
158+
$IndexContent += $NewAndOldArchBadgeMd + "`r`n"
159+
$IndexContent += "`r`n"
160+
161+
$AllTypesByKind.Keys | Where-Object { $_ -ne 'unknown' } | Sort-Object | ForEach-Object {
162+
$IndexContent += "## $($_.Substring(0,1).ToUpper())$($_.Substring(1))$($_.EndsWith("s") ? "es" : "s")`r`n"
163+
$AllTypesByKind[$_] | Sort-Object | ForEach-Object {
164+
$IndexContent += "- [$_]($_)`r`n"
165+
}
166+
$IndexContent += "`r`n"
167+
}
168+
169+
$IndexContent = $IndexContent.Trim()
170+
171+
$IndexPath = (Join-Path $OutputDocsPath "index-api-windows.md")
172+
173+
Write-Host "Creating `"$IndexPath`""
174+
$IndexContent | Out-File -Encoding utf8NoBOM $IndexPath
175+
176+
# Update sidebar
177+
$SidebarsFile = Join-Path $RepoRoot "website/sidebars.json"
178+
$SidebarsJson = Get-Content -Path $SidebarsFile -Raw | ConvertFrom-Json
179+
$NativeApiEntries = @()
180+
181+
$NativeApiEntries += "native-api/Native-API-Reference"
182+
183+
$AllTypesByKind.Keys | Where-Object { $_ -ne 'unknown' } | Sort-Object | ForEach-Object {
184+
$KindObject = @{}
185+
$KindObject['type'] = 'subcategory'
186+
$KindObject['label'] = "$($_.Substring(0,1).ToUpper())$($_.Substring(1))$($_.EndsWith("s") ? "es" : "s")"
187+
$KindObject['ids'] = @()
188+
$AllTypesByKind[$_] | Sort-Object | ForEach-Object {
189+
$KindObject['ids'] += "native-api/$_"
190+
}
191+
$NativeApiEntries += $KindObject
192+
}
193+
194+
$SidebarsJson.apis."Native API (Windows)" = $NativeApiEntries
195+
196+
Write-Host "Updating `"$SidebarsFile`""
197+
$SidebarsJson | ConvertTo-Json -Depth 4 | Set-Content -Path $SidebarsFile
198+
}
199+
200+
[string] $RepoRoot = Resolve-Path "$PSScriptRoot/../.."
201+
202+
$StartingLocation = Get-Location
203+
Set-Location -Path $RepoRoot
204+
205+
try
206+
{
207+
Write-Host "UpdateNativeApiDocs -BuildId $BuildId"
208+
209+
$DownloadPath = Join-Path $env:TEMP "UpdateNativeApiDocs-$BuildId"
210+
Write-Debug "Downloading artifacts to `"$DownloadPath`""
211+
if (Test-Path $DownloadPath)
212+
{
213+
Write-Debug "Deleting existing `"$DownloadPath`""
214+
Remove-Item -Path $DownloadPath -Recurse -Force
215+
}
216+
217+
Write-Debug "Creating new `"$DownloadPath`""
218+
New-Item $DownloadPath -ItemType "Directory" | Out-Null
219+
220+
Write-Debug "Downloading WinRT API docs from $BuildId"
221+
[string]$OldArchDocsPath = Download-BuildArtifact -BuildId $BuildId -ArtifactName "WinRT Api docs - Universal Build X64Debug-1" -DestPath $DownloadPath
222+
[string]$NewArchDocsPath = Download-BuildArtifact -BuildId $BuildId -ArtifactName "WinRT Api docs - Universal Build X64DebugFabric-1" -DestPath $DownloadPath
223+
224+
Merge-WinRtApiDocs -OldArchDocsPath $OldArchDocsPath -NewArchDocsPath $NewArchDocsPath -RepoRoot $RepoRoot -Clean $Clean
225+
}
226+
finally
227+
{
228+
Set-Location -Path $StartingLocation
229+
}
230+
231+
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)