[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, 68 insertions, 65 deletions

diff --git a/scripts/cmake/vcpkg_configure_cmake.cmake b/scripts/cmake/vcpkg_configure_cmake.cmake
index 2f22d34a1..8800d45eb 100644
--- a/scripts/cmake/vcpkg_configure_cmake.cmake
+++ b/scripts/cmake/vcpkg_configure_cmake.cmake
@@ -1,68 +1,71 @@
-## # vcpkg_configure_cmake
-##
-## Configure CMake for Debug and Release builds of a project.
-##
-## ## Usage
-## ```cmake
-## vcpkg_configure_cmake(
-##     SOURCE_PATH <${SOURCE_PATH}>
-##     [PREFER_NINJA]
-##     [DISABLE_PARALLEL_CONFIGURE]
-##     [NO_CHARSET_FLAG]
-##     [GENERATOR <"NMake Makefiles">]
-##     [OPTIONS <-DUSE_THIS_IN_ALL_BUILDS=1>...]
-##     [OPTIONS_RELEASE <-DOPTIMIZE=1>...]
-##     [OPTIONS_DEBUG <-DDEBUGGABLE=1>...]
-## )
-## ```
-##
-## ## Parameters
-## ### SOURCE_PATH
-## Specifies the directory containing the `CMakeLists.txt`.
-## By convention, this is usually set in the portfile as the variable `SOURCE_PATH`.
-##
-## ### PREFER_NINJA
-## Indicates that, when available, Vcpkg should use Ninja to perform the build.
-## This should be specified unless the port is known to not work under Ninja.
-##
-## ### DISABLE_PARALLEL_CONFIGURE
-## Disables running the CMake configure step in parallel.
-## This is needed for libraries which write back into their source directory during configure.
-##
-## This also disables CMAKE_DISABLE_SOURCE_CHANGES.
-##
-## ### NO_CHARSET_FLAG
-## Disables passing `utf-8` as the default character set to `CMAKE_C_FLAGS` and `CMAKE_CXX_FLAGS`.
-##
-## This is needed for libraries that set their own source code's character set.
-##
-## ### GENERATOR
-## Specifies the precise generator to use.
-##
-## This is useful if some project-specific buildsystem has been wrapped in a cmake script that won't perform an actual build.
-## If used for this purpose, it should be set to `"NMake Makefiles"`.
-##
-## ### OPTIONS
-## Additional options passed to CMake during the configuration.
-##
-## ### OPTIONS_RELEASE
-## Additional options passed to CMake during the Release configuration. These are in addition to `OPTIONS`.
-##
-## ### OPTIONS_DEBUG
-## Additional options passed to CMake during the Debug configuration. These are in addition to `OPTIONS`.
-##
-## ### LOGNAME
-## Name of the log to write the output of the configure call to.
-##
-## ## Notes
-## This command supplies many common arguments to CMake. To see the full list, examine the source.
-##
-## ## Examples
-##
-## * [zlib](https://github.com/Microsoft/vcpkg/blob/master/ports/zlib/portfile.cmake)
-## * [cpprestsdk](https://github.com/Microsoft/vcpkg/blob/master/ports/cpprestsdk/portfile.cmake)
-## * [poco](https://github.com/Microsoft/vcpkg/blob/master/ports/poco/portfile.cmake)
-## * [opencv](https://github.com/Microsoft/vcpkg/blob/master/ports/opencv/portfile.cmake)
+#[===[.md:
+# vcpkg_configure_cmake
+
+Configure CMake for Debug and Release builds of a project.
+
+## Usage
+```cmake
+vcpkg_configure_cmake(
+    SOURCE_PATH <${SOURCE_PATH}>
+    [PREFER_NINJA]
+    [DISABLE_PARALLEL_CONFIGURE]
+    [NO_CHARSET_FLAG]
+    [GENERATOR <"NMake Makefiles">]
+    [OPTIONS <-DUSE_THIS_IN_ALL_BUILDS=1>...]
+    [OPTIONS_RELEASE <-DOPTIMIZE=1>...]
+    [OPTIONS_DEBUG <-DDEBUGGABLE=1>...]
+)
+```
+
+## Parameters
+### SOURCE_PATH
+Specifies the directory containing the `CMakeLists.txt`.
+By convention, this is usually set in the portfile as the variable `SOURCE_PATH`.
+
+### PREFER_NINJA
+Indicates that, when available, Vcpkg should use Ninja to perform the build.
+This should be specified unless the port is known to not work under Ninja.
+
+### DISABLE_PARALLEL_CONFIGURE
+Disables running the CMake configure step in parallel.
+This is needed for libraries which write back into their source directory during configure.
+
+This also disables CMAKE_DISABLE_SOURCE_CHANGES.
+
+### NO_CHARSET_FLAG
+Disables passing `utf-8` as the default character set to `CMAKE_C_FLAGS` and `CMAKE_CXX_FLAGS`.
+
+This is needed for libraries that set their own source code's character set.
+
+### GENERATOR
+Specifies the precise generator to use.
+
+This is useful if some project-specific buildsystem has been wrapped in a cmake script that won't perform an actual build.
+If used for this purpose, it should be set to `"NMake Makefiles"`.
+
+### OPTIONS
+Additional options passed to CMake during the configuration.
+
+### OPTIONS_RELEASE
+Additional options passed to CMake during the Release configuration. These are in addition to `OPTIONS`.
+
+### OPTIONS_DEBUG
+Additional options passed to CMake during the Debug configuration. These are in addition to `OPTIONS`.
+
+### LOGNAME
+Name of the log to write the output of the configure call to.
+
+## Notes
+This command supplies many common arguments to CMake. To see the full list, examine the source.
+
+## Examples
+
+* [zlib](https://github.com/Microsoft/vcpkg/blob/master/ports/zlib/portfile.cmake)
+* [cpprestsdk](https://github.com/Microsoft/vcpkg/blob/master/ports/cpprestsdk/portfile.cmake)
+* [poco](https://github.com/Microsoft/vcpkg/blob/master/ports/poco/portfile.cmake)
+* [opencv](https://github.com/Microsoft/vcpkg/blob/master/ports/opencv/portfile.cmake)
+#]===]
+
 function(vcpkg_configure_cmake)
     # parse parameters such that semicolons in arguments to OPTIONS don't get erased
     cmake_parse_arguments(PARSE_ARGV 0 _csc