[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

2 files changed, 46 insertions, 0 deletions

diff --git a/scripts/azure-pipelines/azure-pipelines.yml b/scripts/azure-pipelines/azure-pipelines.yml
index 1a2852ced..03bf38e4c 100644
--- a/scripts/azure-pipelines/azure-pipelines.yml
+++ b/scripts/azure-pipelines/azure-pipelines.yml
@@ -39,11 +39,27 @@ stages:
         filePath: 'scripts/azure-pipelines/windows/Check-ManifestFormatting.ps1'

         arguments: '-Root .'

         pwsh: true

+- stage: check_documentation_generation

+  displayName: Check if the documentation has been regenerated correctly

+  pool: $(windows-pool)

+  dependsOn: []

+  jobs:

+  - job:

+    workspace:

+      clean: resources

+    steps:

+    - task: Powershell@2

+      displayName: 'Check documentation generation'

+      inputs:

+        filePath: 'scripts/azure-pipelines/windows/Check-CMakeFunctionDocumentation.ps1'

+        arguments: '-Root .'

+        pwsh: true

 - stage: run_port_ci

   displayName: 'Run the Port CI'

   dependsOn:

   - check_cxx_formatting

   - check_manifest_formatting

+  - check_documentation_generation

   jobs:

   - template: windows/azure-pipelines.yml

     parameters:

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
+}