/
Generate-DocIndex.ps1
196 lines (182 loc) · 8.77 KB
/
Generate-DocIndex.ps1
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
# Generates an index page for cataloging different versions of the Docs
[CmdletBinding()]
Param (
$DocFx,
$RepoRoot,
$DocGenDir,
$DocOutDir = "${RepoRoot}/docfx_project",
$DocfxJsonPath = "${PSScriptRoot}\docfx.json",
$MainJsPath = "${PSScriptRoot}\templates\matthews\styles\main.js"
)
. "${PSScriptRoot}\..\scripts\common.ps1"
$GetGithubIoDocIndexFn = "Get-${Language}-GithubIoDocIndex"
# Given the metadata url under https://github.com/Azure/azure-sdk/tree/master/_data/releases/latest,
# the function will return the csv metadata back as part of response.
function Get-CSVMetadata ([string]$MetadataUri) {
$metadataResponse = Invoke-RestMethod -Uri $MetadataUri -method "GET" -MaximumRetryCount 3 -RetryIntervalSec 10 | ConvertFrom-Csv
return $metadataResponse
}
# Given the github io blob storage url and language regex,
# the helper function will return a list of artifact names.
function Get-BlobStorage-Artifacts($blobStorageUrl, $blobDirectoryRegex, $blobArtifactsReplacement) {
LogDebug "Reading artifact from storage blob ..."
$returnedArtifacts = @()
$pageToken = ""
Do {
$resp = ""
if (!$pageToken) {
# First page call.
$resp = Invoke-RestMethod -Method Get -Uri $blobStorageUrl
}
else {
# Next page call
$blobStorageUrlPageToken = $blobStorageUrl + "&marker=$pageToken"
$resp = Invoke-RestMethod -Method Get -Uri $blobStorageUrlPageToken
}
# Convert to xml documents.
$xmlDoc = [xml](removeBomFromString $resp)
foreach ($elem in $xmlDoc.EnumerationResults.Blobs.BlobPrefix) {
# What service return like "dotnet/Azure.AI.Anomalydetector/", needs to fetch out "Azure.AI.Anomalydetector"
$artifact = $elem.Name -replace $blobDirectoryRegex, $blobArtifactsReplacement
$returnedArtifacts += $artifact
}
# Fetch page token
$pageToken = $xmlDoc.EnumerationResults.NextMarker
} while ($pageToken)
return $returnedArtifacts
}
# The sequence of Bom bytes differs by different encoding.
# The helper function here is only to strip the utf-8 encoding system as it is used by blob storage list api.
# Return the original string if not in BOM utf-8 sequence.
function RemoveBomFromString([string]$bomAwareString) {
if ($bomAwareString.length -le 3) {
return $bomAwareString
}
$bomPatternByteArray = [byte[]] (0xef, 0xbb, 0xbf)
# The default encoding for powershell is ISO-8859-1, so converting bytes with the encoding.
$bomAwareBytes = [Text.Encoding]::GetEncoding(28591).GetBytes($bomAwareString.Substring(0, 3))
if (@(Compare-Object $bomPatternByteArray $bomAwareBytes -SyncWindow 0).Length -eq 0) {
return $bomAwareString.Substring(3)
}
return $bomAwareString
}
function Get-TocMapping {
Param (
[Parameter(Mandatory = $true)] [Object[]] $metadata,
[Parameter(Mandatory = $true)] [String[]] $artifacts
)
# Used for sorting the toc display order
$orderServiceMapping = @{}
foreach ($artifact in $artifacts) {
$packageInfo = $metadata | ? {$_.Package -eq $artifact}
if ($packageInfo -and $packageInfo[0].Hide -eq 'true') {
LogDebug "The artifact $artifact set 'Hide' to 'true'."
continue
}
$serviceName = ""
$displayName = ""
if (!$packageInfo) {
LogWarning "There is no artifact $artifact. Please check csv of Azure/azure-sdk/_data/release/latest repo if this is intended. "
# If no service name retrieved, print out warning message, and put it into Other page.
$serviceName = "Other"
}
elseif (!$packageInfo[0].ServiceName) {
LogWarning "There is no service name for artifact $artifact. Please check csv of Azure/azure-sdk/_data/release/latest repo if this is intended. "
# If no service name retrieved, print out warning message, and put it into Other page.
$serviceName = "Other"
$displayName = $packageInfo[0].DisplayName.Trim()
}
else {
if ($packageInfo.Length -gt 1) {
LogWarning "There are more than 1 packages fetched out for artifact $artifact. Please check csv of Azure/azure-sdk/_data/release/latest repo if this is intended. "
}
$serviceName = $packageInfo[0].ServiceName.Trim()
$displayName = $packageInfo[0].DisplayName.Trim()
}
$orderServiceMapping[$artifact] = @($serviceName, $displayName)
}
return $orderServiceMapping
}
function GenerateDocfxTocContent([Hashtable]$tocContent, [String]$lang) {
LogDebug "Start generating the docfx toc and build docfx site..."
LogDebug "Initializing Default DocFx Site..."
& $($DocFx) init -q -o "${DocOutDir}"
# The line below is used for testing in local
#docfx init -q -o "${DocOutDir}"
LogDebug "Copying template and configuration..."
New-Item -Path "${DocOutDir}" -Name "templates" -ItemType "directory" -Force
Copy-Item "${DocGenDir}/templates/*" -Destination "${DocOutDir}/templates" -Force -Recurse
Copy-Item "${DocGenDir}/docfx.json" -Destination "${DocOutDir}/" -Force
$YmlPath = "${DocOutDir}/api"
New-Item -Path $YmlPath -Name "toc.yml" -Force
$visitedService = @{}
# Sort and display toc service name by alphabetical order, and then sort artifact by order.
foreach ($serviceMapping in ($tocContent.GetEnumerator() | Sort-Object Value[0], Key)) {
$artifact = $serviceMapping.Key
$serviceName = $serviceMapping.Value[0]
$displayName = $serviceMapping.Value[1]
$fileName = ($serviceName -replace '\s', '').ToLower().Trim()
if ($visitedService.ContainsKey($serviceName)) {
if ($displayName) {
Add-Content -Path "$($YmlPath)/${fileName}.md" -Value "#### $artifact`n##### ($displayName)"
}
else {
Add-Content -Path "$($YmlPath)/${fileName}.md" -Value "#### $artifact"
}
}
else {
Add-Content -Path "$($YmlPath)/toc.yml" -Value "- name: ${serviceName}`r`n href: ${fileName}.md"
New-Item -Path $YmlPath -Name "${fileName}.md" -Force
if ($displayName) {
Add-Content -Path "$($YmlPath)/${fileName}.md" -Value "#### $artifact`n##### ($displayName)"
}
else {
Add-Content -Path "$($YmlPath)/${fileName}.md" -Value "#### $artifact"
}
$visitedService[$serviceName] = $true
}
}
# Generate toc homepage.
LogDebug "Creating Site Title and Navigation..."
New-Item -Path "${DocOutDir}" -Name "toc.yml" -Force
Add-Content -Path "${DocOutDir}/toc.yml" -Value "- name: Azure SDK for $lang APIs`r`n href: api/`r`n homepage: api/index.md"
LogDebug "Copying root markdowns"
Copy-Item "$($RepoRoot)/README.md" -Destination "${DocOutDir}/api/index.md" -Force
Copy-Item "$($RepoRoot)/CONTRIBUTING.md" -Destination "${DocOutDir}/api/CONTRIBUTING.md" -Force
LogDebug "Building site..."
& $($DocFx) build "${DocOutDir}/docfx.json"
# The line below is used for testing in local
#docfx build "${DocOutDir}/docfx.json"
Copy-Item "${DocGenDir}/assets/logo.svg" -Destination "${DocOutDir}/_site/" -Force
}
function Mutate-Files {
Param (
[Parameter(Mandatory=$true)] [String]$appTitle,
[Parameter(Mandatory=$true)] [String]$lang,
[Parameter(Mandatory=$true)] [String]$indexhtmlloc,
[Parameter(Mandatory=$false)] [String]$packageRegex = "`"`"",
[Parameter(Mandatory=$false)] [String]$regexReplacement = ""
)
# Update docfx.json
$docfxContent = Get-Content -Path $DocfxJsonPath -Raw
$docfxContent = $docfxContent -replace "`"_appTitle`": `"`"", "`"_appTitle`": `"$appTitle`""
$docfxContent = $docfxContent -replace "`"_appFooter`": `"`"", "`"_appFooter`": `"$appTitle`""
Set-Content -Path $DocfxJsonPath -Value $docfxContent
# Update main.js var lang
$mainJsContent = Get-Content -Path $MainJsPath -Raw
$mainJsContent = $mainJsContent -replace "var SELECTED_LANGUAGE = ''", "var SELECTED_LANGUAGE = '$lang'"
# Update main.js var index html
$mainJsContent = $mainJsContent -replace "var INDEX_HTML = ''", "var INDEX_HTML = '$indexhtmlloc'"
# Update main.js package regex and replacement
$mainJsContent = $mainJsContent -replace "var PACKAGE_REGEX = ''", "var PACKAGE_REGEX = $packageRegex"
$mainJsContent = $mainJsContent -replace "var PACKAGE_REPLACEMENT = ''", "var PACKAGE_REPLACEMENT = `"$regexReplacement`""
Set-Content -Path $MainJsPath -Value $mainJsContent -NoNewline
}
if ($GetGithubIoDocIndexFn -and (Test-Path "function:$GetGithubIoDocIndexFn"))
{
&$GetGithubIoDocIndexFn
}
else
{
LogWarning "The function '$GetGithubIoDocIndexFn' was not found."
}