docs: Enable markdown linting and spell checking with related fixes

unoplatform · Jun 3, 2024 · 20b6da7 · 20b6da7
1 parent f53b4b4
commit 20b6da7
Show file tree

Hide file tree

Showing 43 changed files with 771 additions and 285 deletions.
diff --git a/.vsts-ci.yml b/.vsts-ci.yml
@@ -1,22 +1,57 @@
+trigger:
+  branches:
+    include:
+      - main
+      - release/stable/*
+      - feature/*
 
-jobs:
-- template: .vsts-ci-packages.yml
-  parameters:
-    jobName: Packages
+pr:
+  branches:
+    include:
+      - main
+      - release/stable/*
+      - feature/*
 
-- template: .vsts-ci-linux.yml
-  parameters:
-    jobName: Linux_Tests
-    linux_container: unoplatform/wasm-build:3.0
+stages:
+- stage: Determine_Changes
+  displayName: Determine Changes
+  jobs:
+  - template: build/ci/stage-determine-changes.yml
 
-- template: .vsts-ci-windows-tests.yml
-  parameters:
-    jobName: Windows_Tests
-    linux_container: unoplatform/wasm-build:3.0
+- stage: Docs_Validations
+  displayName: Docs Validations
+  dependsOn: Determine_Changes
+  # Trigger this stage when docs files are changed
+  condition: or(eq(dependencies.Determine_Changes.outputs['evaluate_changes.DetermineChanges.docsOnly'], 'true'), eq(dependencies.Determine_Changes.outputs['evaluate_changes.DetermineChanges.mixedChanges'], 'true'))
+  jobs:
+  - template: build/ci/stage-docs-validations.yml
 
-- template: .vsts-ci-macos.yml
-  parameters:
-    jobName: macOS_Tests
-    vmImage: macOS-12
+- stage: Packages
+  displayName: Packages
+  dependsOn: Determine_Changes
+  # Don't trigger this stage if only docs files are changed
+  condition: ne(dependencies.Determine_Changes.outputs['evaluate_changes.DetermineChanges.docsOnly'], 'true')
+  jobs:
+  - template: build/ci/stage-build-packages.yml
+    parameters:
+      jobName: Packages
 
-- template: .vsts-ci-wsl-tests.yml
+- stage: Build_Tests
+  displayName: Build Tests
+  dependsOn: Determine_Changes
+  # Don't trigger this stage if only docs files are changed
+  condition: ne(dependencies.Determine_Changes.outputs['evaluate_changes.DetermineChanges.docsOnly'], 'true')
+  jobs:
+    - template: build/stage-build-linux-tests.yml
+      parameters:
+        jobName: Linux_Tests
+        linux_container: unoplatform/wasm-build:3.0
+    - template: build/stage-build-windows-tests.yml
+      parameters:
+        jobName: Windows_Tests
+        linux_container: unoplatform/wasm-build:3.0
+    - template: build/stage-build-macos-tests.yml
+      parameters:
+        jobName: macOS_Tests
+        vmImage: macOS-12
+    - template: build/stage-build-wsl-tests.yml
diff --git a/Readme.md b/Readme.md
@@ -13,6 +13,7 @@ This package only provides the bootstrapping features to run a .NET assembly and
 This package is based on the excellent work from @praeclarum's [OOui Wasm MSBuild task](https://github.com/praeclarum/Ooui).
 
 ## Documentation
+
 - [Using the bootstrapper](doc/using-the-bootstrapper.md)
 - [Debugger support](doc/debugger-support.md)
 - [Deploy and publish](doc/deploy-and-publish.md)
@@ -35,7 +36,7 @@ This package is based on the excellent work from @praeclarum's [OOui Wasm MSBuil
   - [Profiling](doc/features-profiling.md)
   - [Node JS](doc/features-node-js.md)
   - [Nuget package overrides](doc/features-nuget-package-overrides.md)
-  - [Prefechting](doc/features-prefetch.md)
+  - [Prefetching](doc/features-prefetch.md)
   - [PWA Support](doc/features-pwa.md)
   - [4GB Support](doc/features-4gb.md)
   - [HttpRequestMessage Extensions](doc/features-httprequestmessage-extensions.md)

diff --git a/build/ci/.markdownlint.json b/build/ci/.markdownlint.json
@@ -0,0 +1,9 @@
+{
+	"default": true,
+	"line-length": false,
+	"commands-show-output": false,
+	"no-bare-urls": false,
+	"no-inline-html": false,
+	"no-duplicate-heading": false,
+	"MD051": false
+}
diff --git a/build/ci/cspell.json b/build/ci/cspell.json
@@ -0,0 +1,202 @@
+{
+	"version": "0.2",
+	"language": "en",
+	"words": [
+		"Avalonia",
+		"ambiently",
+		"binlog",
+		"Blazor",
+		"blockquotes",
+		"Bootstrapper",
+		"brotli",
+		"browsersync",
+		"bytecode",
+		"Callout",
+		"chatops",
+		"codebases",
+		"Codespace",
+		"Codespaces",
+		"Contoso",
+		"Cupertino",
+		"customizability",
+		"databinding",
+		"datacontext",
+		"datagrid",
+		"devs",
+		"Dismissable",
+		"Docfx",
+		"ellipsize",
+		"Expando",
+		"flyouts",
+		"Framebuffer",
+		"Gamepad",
+		"gamepads",
+		"Geolocation",
+		"globbing",
+		"Gyrometer",
+		"Hanja",
+		"hectopascals",
+		"Inlines",
+		"keychain",
+		"laggy",
+		"layouter",
+		"layouting",
+		"Listview",
+		"LLRM",
+		"mergeable",
+		"MSAL",
+		"msbuild",
+		"MVUX",
+		"MVVM",
+		"NETSDK",
+		"netstandard",
+		"oidc",
+		"Omnisharp",
+		"overscroll",
+		"Packt",
+		"parameterless",
+		"pickable",
+		"Pluralsight",
+		"POSIX",
+		"reentrantly",
+		"Resizetizer",
+		"resw",
+		"roadmap",
+		"sandboxed",
+		"Segoe",
+		"Silverlight",
+		"Skia",
+		"skiasharp",
+		"Storyboarded",
+		"struct",
+		"Syncfusion",
+		"templatable",
+		"templating",
+		"timespan",
+		"Tizen",
+		"TLDR",
+		"toolkits",
+		"triaging",
+		"UI's",
+		"unmanaged",
+		"Uno's",
+		"unoplatform",
+		"UWP's",
+		"VSIX",
+		"walkthrough",
+		"WEBASSEMBLY",
+		"Haptics"
+	],
+	"ignoreWords": [
+		"ADAL",
+		"addin",
+		"AEHD",
+		"appsettings",
+		"Authenticode",
+		"automagically",
+		"Divio's",
+		"emcc",
+		"emscripten",
+		"Findlay",
+		"Flatpickr",
+		"Giesel",
+		"GNSS",
+		"GPIO",
+		"Grigorik",
+		"hdpi",
+		"Headered",
+		"Hoefling",
+		"HRESULT",
+		"Icaza",
+		"IDBFS",
+		"Ilya",
+		"Infragistics",
+		"jonathanpeppers's",
+		"Krueger",
+		"libgtk",
+		"Liu's",
+		"Logpoints",
+		"macios",
+		"Matteo",
+		"McCaffrey",
+		"mdpi",
+		"Mergify",
+		"mlaunch",
+		"muxc",
+		"netstd",
+		"nventive",
+		"odel",
+		"Onoh",
+		"pdate",
+		"Ronica",
+		"Serilog",
+		"Singh",
+		"slnf",
+		"Stetho",
+		"Talkin",
+		"UADO",
+		"Udemy",
+		"UNOB",
+		"unpackaged",
+		"winappsdk",
+		"winui",
+		"xhdpi",
+		"xxhdpi",
+		"xxxhdpi",
+		"Yowza"
+	],
+	"patterns": [
+		{
+			"name": "Markdown uid",
+			"pattern": "^(?=uid:).*$",
+			"description": ""
+		},
+		{
+			"name": "Markdown links",
+			"pattern": "\\((.*)\\)",
+			"description": ""
+		},
+		{
+			"name": "Markdown code blocks",
+			"pattern": "/^(\\s*`{3,}).*[\\s\\S]*?^\\1/gmx",
+			"description": "Taken from the cSpell example at https://cspell.org/configuration/patterns/#verbose-regular-expressions"
+		},
+		{
+			"name": "Inline code blocks",
+			"pattern": "\\`([^\\`\\r\\n]+?)\\`",
+			"description": "https://stackoverflow.com/questions/41274241/how-to-capture-inline-markdown-code-but-not-a-markdown-code-fence-with-regex"
+		},
+		{
+			"name": "Link contents",
+			"pattern": "\\<a(.*)\\>",
+			"description": ""
+		},
+		{
+			"name": "Snippet references",
+			"pattern": "-- snippet:(.*)",
+			"description": ""
+		},
+		{
+			"name": "Snippet references 2",
+			"pattern": "\\<\\[sample:(.*)",
+			"description": "another kind of snippet reference"
+		},
+		{
+			"name": "Multi-line code blocks",
+			"pattern": "/^\\s*```[\\s\\S]*?^\\s*```/gm"
+		}
+	],
+	"ignoreRegExpList": [
+		"Markdown uid",
+		"Markdown links",
+		"Markdown code blocks",
+		"Inline code blocks",
+		"Link contents",
+		"Snippet references",
+		"Snippet references 2",
+		"Multi-line code blocks"
+	],
+	"ignorePaths": [
+		"../doc/index.md"
+	]
+}
diff --git a/.vsts-ci-linux.yml → build/ci/stage-build-linux-tests.yml b/.vsts-ci-linux.yml → build/ci/stage-build-linux-tests.yml
diff --git a/.vsts-ci-macos.yml → build/ci/stage-build-macos-tests.yml b/.vsts-ci-macos.yml → build/ci/stage-build-macos-tests.yml
diff --git a/.vsts-ci-packages.yml → build/ci/stage-build-packages.yml b/.vsts-ci-packages.yml → build/ci/stage-build-packages.yml
diff --git a/.vsts-ci-windows-tests.yml → build/ci/stage-build-windows-tests.yml b/.vsts-ci-windows-tests.yml → build/ci/stage-build-windows-tests.yml
diff --git a/.vsts-ci-wsl-tests.yml → build/ci/stage-build-wsl-tests.yml b/.vsts-ci-wsl-tests.yml → build/ci/stage-build-wsl-tests.yml
diff --git a/build/ci/stage-determine-changes.yml b/build/ci/stage-determine-changes.yml
@@ -0,0 +1,77 @@
+jobs:
+- job: evaluate_changes
+  displayName: 'Check for Doc Only Changes'
+  pool:
+    vmImage: 'ubuntu-latest'
+  steps:
+  - powershell: |
+      # Determine the context of the build (PR or push) and set the target branch accordingly
+      $isPR = "$(Build.Reason)" -eq "PullRequest"
+
+      # Normalize the target branch name for PR builds or default to 'master' for push builds
+      $targetBranchName = $isPR ? "$(System.PullRequest.TargetBranch)" -replace 'refs/heads/', '' : "master"
+      Write-Host "Build context determined: $(if ($isPR) { 'Pull Request targeting ' + $targetBranchName } else { 'Push' })"
+
+      # Fetch the target or default base branch and determine the merge base
+      git fetch origin $targetBranchName
+      $mergeBase = git merge-base HEAD "origin/$targetBranchName"
+      Write-Host "Merge base with '$targetBranchName' identified at $mergeBase"
+
+      Write-Host "Comparing changes from $mergeBase..."
+      $gitDiffCommand = "git diff $mergeBase --name-only"
+      $changedFiles = Invoke-Expression $gitDiffCommand
+      $docsOnly = $false
+      $nonDocsOnly = $false
+      $mixedChanges = $false
+      $docFiles = 0
+      $nonDocFiles = 0
+
+      if ($changedFiles) {
+          Write-Host "Changed files:"
+          Write-Host $changedFiles
+      } else {
+          Write-Host "No files have changed."
+      }
+
+      foreach ($file in $changedFiles -split "`n") {
+        # Identifying changes as documentation if they occur:
+        # Within the doc folder, or
+        # Are Markdown files at the root level (with no subdirectories involved), or
+        # Are Markdown files within the .github folder (including its subdirectories)
+          $isDoc = $file.StartsWith("doc/") -or              # Files in the 'doc/' directory
+            ($file -match "^[^/]+\.md$") -or                 # Markdown files in the root directory
+            ($file -match "^\.github/.*\.md$") -or           # Markdown files in the '.github' directory
+            ($file -match "^\.(markdownlint|cspell)\.json$") # Specific JSON files: .markdownlint.json and cspell.json
+  
+          if ($isDoc) {
+              $docFiles++
+          } else {
+              $nonDocFiles++
+          }
+      }
+
+      Write-Host "Documentation files changed: $docFiles"
+      Write-Host "Non-documentation files changed: $nonDocFiles"
+
+      if ($docFiles -gt 0 -and $nonDocFiles -eq 0) {
+          $docsOnly = $true
+          Write-Host "All changes are documentation-only."
+      } elseif ($docFiles -gt 0 -and $nonDocFiles -gt 0) {
+          $mixedChanges = $true
+          Write-Host "Mixed changes detected: Both documentation and non-documentation files have been modified."
+      } elseif ($nonDocFiles -gt 0) {
+          $nonDocsOnly = $true
+          Write-Host "Non-documentation changes detected."
+      }
+
+      # Explicitly write the final values for clarity
+      Write-Host "Final values:"
+      Write-Host "docsOnly: $docsOnly"
+      Write-Host "nonDocsOnly: $nonDocsOnly"
+      Write-Host "mixedChanges: $mixedChanges"
+
+      # Output the results as pipeline variables
+      Write-Host "##vso[task.setvariable variable=docsOnly;isOutput=true]$docsOnly"
+      Write-Host "##vso[task.setvariable variable=nonDocsOnly;isOutput=true]$nonDocsOnly"
+      Write-Host "##vso[task.setvariable variable=mixedChanges;isOutput=true]$mixedChanges"
+    name: DetermineChanges