[vcpkg docs] Check for documentation generation in CI (#14614)

* [vcpkg docs] Change how documenting port functions works

Instead of using `##`, use comment blocks for documentation.

Also, add some minor docs and change RST -> MD
so we actually get docs generated.

* add CI stuff

* regenerate docs

* fix vcpkg_find_acquire_program to not use _execute_process

1 files changed, 30 insertions, 0 deletions

diff --git a/scripts/azure-pipelines/windows/Check-CMakeFunctionDocumentation.ps1 b/scripts/azure-pipelines/windows/Check-CMakeFunctionDocumentation.ps1
new file mode 100644
index 000000000..5505c3401
--- /dev/null
+++ b/scripts/azure-pipelines/windows/Check-CMakeFunctionDocumentation.ps1
@@ -0,0 +1,30 @@
+[CmdletBinding()]
+Param(
+    [Parameter(Mandatory=$True)]
+    [string]$Root
+)
+
+if (-not (Test-Path "$Root/.vcpkg-root"))
+{
+    Write-Error "The vcpkg root was not at $Root"
+    throw
+}
+
+& "$Root/docs/regenerate.ps1" -VcpkgRoot $Root -WarningAction 'Stop'
+
+$changedFiles = & "$PSScriptRoot/Get-ChangedFiles.ps1" -Directory "$Root/docs"
+if ($null -ne $changedFiles)
+{
+    $msg = @(
+        "",
+        "The documentation files do not seem to have been regenerated.",
+        "Please re-run `docs/regenerate.ps1`."
+    )
+    $msg += ""
+
+    $msg += "This should produce the following diff:"
+    $msg += git diff "$Root/docs"
+
+    Write-Error ($msg -join "`n")
+    throw
+}