[vcpkg-docs] Rework documentation for compatibility with readthedocs.io and MkDocs.

1 files changed, 56 insertions, 43 deletions

diff --git a/scripts/cmake/vcpkg_build_msbuild.cmake b/scripts/cmake/vcpkg_build_msbuild.cmake
index 6fe3f5aa0..1e3c85ba2 100644
--- a/scripts/cmake/vcpkg_build_msbuild.cmake
+++ b/scripts/cmake/vcpkg_build_msbuild.cmake
@@ -1,46 +1,59 @@
-#.rst:
-# .. command:: vcpkg_build_msbuild
-#
-#  Build a msbuild-based project.
-#
-#  ::
-#  vcpkg_build_msbuild(PROJECT_PATH <sln_project_path>
-#                      [RELEASE_CONFIGURATION <release_configuration>] # (default = "Release")
-#                      [DEBUG_CONFIGURATION <debug_configuration>] @ (default = "Debug")
-#                      [TARGET_PLATFORM_VERSION <windows_target_platform_version>]
-#                      [PLATFORM <platform>] # (default = "${TRIPLET_SYSTEM_ARCH}")
-#                      [PLATFORM_TOOLSET <platform_toolset>] # (default = "${VCPKG_PLATFORM_TOOLSET}")
-#                      [OPTIONS arg1 [arg2 ...]]
-#                      [OPTIONS_RELEASE arg1 [arg2 ...]]
-#                      [OPTIONS_DEBUG arg1 [arg2 ...]]
-#                      )
-#
-#  ``PROJECT_PATH``
-#    The path to the *.sln msbuild project file.
-#  ``RELEASE_CONFIGURATION``
-#    The configuration (``/p:Configuration`` msbuild parameter)
-#    used for Release builds.
-#  ``DEBUG_CONFIGURATION``
-#    The configuration (``/p:Configuration`` msbuild parameter)
-#    used for Debug builds.
-#  ``TARGET_PLATFORM_VERSION``
-#    The WindowsTargetPlatformVersion (``/p:WindowsTargetPlatformVersion`` msbuild parameter)
-#  ``TARGET``
-#    The MSBuild target to build. (``/t:<TARGET>``)
-#  ``PLATFORM``
-#    The platform (``/p:Platform`` msbuild parameter)
-#    used for the build.
-#  ``PLATFORM_TOOLSET``
-#    The platform toolset (``/p:PlatformToolset`` msbuild parameter)
-#    used for the build.
-#  ``OPTIONS``
-#    The options passed to msbuild for all builds.
-#  ``OPTIONS_RELEASE``
-#    The options passed to msbuild for Release builds.
-#  ``OPTIONS_DEBUG``
-#    The options passed to msbuild for Debug builds.
-#
-
+## # vcpkg_build_msbuild
+##
+## Build an msbuild-based project.
+##
+## ## Usage
+## ```cmake
+## vcpkg_build_msbuild(
+##     PROJECT_PATH <${SOURCE_PATH}/port.sln>
+##     [RELEASE_CONFIGURATION <Release>]
+##     [DEBUG_CONFIGURATION <Debug>]
+##     [TARGET <Build>]
+##     [TARGET_PLATFORM_VERSION <10.0.15063.0>]
+##     [PLATFORM <${TRIPLET_SYSTEM_ARCH}>]
+##     [PLATFORM_TOOLSET <${VCPKG_PLATFORM_TOOLSET}>]
+##     [OPTIONS </p:ZLIB_INCLUDE_PATH=X>...]
+##     [OPTIONS_RELEASE </p:ZLIB_LIB=X>...]
+##     [OPTIONS_DEBUG </p:ZLIB_LIB=X>...]
+## )
+## ```
+##
+## ## Parameters
+## ### PROJECT_PATH
+## The path to the solution (`.sln`) or project (`.vcxproj`) file.
+##
+## ### RELEASE_CONFIGURATION
+## The configuration (``/p:Configuration`` msbuild parameter) used for Release builds.
+##
+## ### DEBUG_CONFIGURATION
+## The configuration (``/p:Configuration`` msbuild parameter)
+## used for Debug builds.
+##
+## ### TARGET_PLATFORM_VERSION
+## The WindowsTargetPlatformVersion (``/p:WindowsTargetPlatformVersion`` msbuild parameter)
+##
+## ### TARGET
+## The MSBuild target to build. (``/t:<TARGET>``)
+##
+## ### PLATFORM
+## The platform (``/p:Platform`` msbuild parameter) used for the build.
+##
+## ### PLATFORM_TOOLSET
+## The platform toolset (``/p:PlatformToolset`` msbuild parameter) used for the build.
+##
+## ### OPTIONS
+## Additional options passed to msbuild for all builds.
+##
+## ### OPTIONS_RELEASE
+## Additional options passed to msbuild for Release builds. These are in addition to `OPTIONS`.
+##
+## ### OPTIONS_DEBUG
+## Additional options passed to msbuild for Debug builds. These are in addition to `OPTIONS`.
+##
+## ## Examples
+##
+## * [libuv](https://github.com/Microsoft/vcpkg/blob/master/ports/libuv/portfile.cmake)
+## * [zeromq](https://github.com/Microsoft/vcpkg/blob/master/ports/zeromq/portfile.cmake)
 
 function(vcpkg_build_msbuild)
     cmake_parse_arguments(_csc "" "PROJECT_PATH;RELEASE_CONFIGURATION;DEBUG_CONFIGURATION;PLATFORM;PLATFORM_TOOLSET;TARGET_PLATFORM_VERSION;TARGET" "OPTIONS;OPTIONS_RELEASE;OPTIONS_DEBUG" ${ARGN})