[docs] Fix broken links and generate documentation for vcpkg-gn (#2…

…4764) * [docs] Fix broken links. Add docs validation pipeline. * [docs][regenerate.ps1] Do not require a README.md in helper ports * [docs] Update validateDocs.yml to point to current main
microsoft · May 20, 2022 · 292067a · 292067a
1 parent f20c7bf
commit 292067a
Show file tree

Hide file tree

Showing 16 changed files with 156 additions and 24 deletions.
diff --git a/.github/workflows/validateDocs.yml b/.github/workflows/validateDocs.yml
@@ -0,0 +1,54 @@
+name: Doc Validation
+
+on:
+  pull_request:
+    paths:
+      - 'docs/**'
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+        with:
+          path: vcpkg
+
+      - name: Checkout Website
+        uses: actions/checkout@v3
+        with:
+          repository: vcpkg/vcpkg.github.io
+          ref: '8ee5cacc91b6e017b5e4236940d9f385c1563598'
+          path: vcpkg.github.io
+
+      - uses: actions/cache@v3
+        with:
+          path: ~/.npm
+          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-node-
+
+      - run: npm ci
+        working-directory: vcpkg.github.io
+
+      - name: Purge existing html files
+        run: rm -rf en
+        working-directory: vcpkg.github.io
+
+      # The current navbar embeds a link to integration.md which no longer exists
+      - name: Ignore navbar
+        run: echo "" > templates/navbar.html
+        working-directory: vcpkg.github.io
+
+      - name: Generate Core Pages
+        run: node scripts/generatePages.js
+        working-directory: vcpkg.github.io
+
+      - name: Generate Docs Pages
+        run: node scripts/generateDocs.js ../vcpkg/docs
+        working-directory: vcpkg.github.io
+
+      - name: Check Links
+        run: VCPKG_VALIDATE_LINKS_ONLY_DOCS=1 node scripts/validateLinks.js
+        working-directory: vcpkg.github.io
diff --git a/docs/README.md b/docs/README.md
@@ -50,11 +50,6 @@ Vcpkg helps you manage C and C++ libraries on Windows, Linux and MacOS. This too
 - [vcpkgx](https://vcpkgx.com/) - Package index + search
 - [vcpkg index](https://vcpkg.dev/) - Package index + search
 
-### Specifications
-
-- [Export](specifications/export-command.md)
-- [Feature Packages](specifications/feature-packages.md)
-
 ### Blog posts
 
 - [Vcpkg Host Dependencies for Cross-Compilation](https://devblogs.microsoft.com/cppblog/vcpkg-host-dependencies/)

diff --git a/docs/about/faq.md b/docs/about/faq.md
@@ -6,7 +6,7 @@ If you want to contribute but don't have a particular library in mind then take
 of [new port requests](https://github.com/Microsoft/vcpkg/issues?q=is%3Aissue+is%3Aopen+label%3Acategory%3Anew-port).
 
 ## Can Vcpkg create pre-built binary packages? What is the binary format used by Vcpkg?
-Yes! See [the `export` command](../users/buildsystems/integration.md#export-command).
+Yes! See the [`export` command](../users/buildsystems/export-command.md).
 
 ## How do I update libraries?
 The `vcpkg update` command lists all packages which are out-of-sync with your current portfiles. To update a package, follow the instructions in the command.
@@ -88,7 +88,7 @@ Vcpkg uses CMake internally as a build scripting language. This is because CMake
 ## Will Vcpkg support downloading compiled binaries from a public or private server?
 We would like to eventually support downloading precompiled binaries, similar to other system package managers.
 
-In a corporate scenario, we currently recommend building the libraries once and distributing the entire vcpkg root directory to everyone else on the project through some raw file transport such as a network share or HTTP host. See the [`export`](../users/buildsystems/integration.md#export) command.
+In a corporate scenario, we currently recommend building the libraries once and distributing the entire vcpkg root directory to everyone else on the project through some raw file transport such as a network share or HTTP host. See the [`export` command](../users/buildsystems/export-command.md).
 
 ## What Visual C++ toolsets are supported?
 We support Visual Studio 2015 Update 3 and above.

diff --git a/docs/maintainers/portfile-functions.md b/docs/maintainers/portfile-functions.md
@@ -74,6 +74,11 @@
 - [vcpkg\_cmake\_configure](ports/vcpkg-cmake/vcpkg_cmake_configure.md)
 - [vcpkg\_cmake\_install](ports/vcpkg-cmake/vcpkg_cmake_install.md)
 
+### [vcpkg-gn](ports/vcpkg-gn.md)
+
+- [vcpkg\_gn\_configure](ports/vcpkg-gn/vcpkg_gn_configure.md)
+- [vcpkg\_gn\_install](ports/vcpkg-gn/vcpkg_gn_install.md)
+
 ### [vcpkg-cmake-config](ports/vcpkg-cmake-config.md)
 
 - [vcpkg\_cmake\_config\_fixup](ports/vcpkg-cmake-config/vcpkg_cmake_config_fixup.md)

diff --git a/docs/maintainers/ports/vcpkg-gn.md b/docs/maintainers/ports/vcpkg-gn.md
@@ -0,0 +1,12 @@
+# vcpkg-cmake
+
+This port contains cmake functions for dealing with a GN buildsystem.
+
+## Example
+
+```cmake
+vcpkg_gn_configure(
+    SOURCE_PATH "${SOURCE_PATH}"
+)
+vcpkg_gn_install()
+```
diff --git a/docs/maintainers/ports/vcpkg-gn/vcpkg_gn_configure.md b/docs/maintainers/ports/vcpkg-gn/vcpkg_gn_configure.md
@@ -0,0 +1,32 @@
+# vcpkg_gn_configure
+
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/ports/vcpkg-gn/vcpkg_gn_configure.md).
+
+Generate Ninja (GN) targets
+
+## Usage:
+```cmake
+vcpkg_gn_configure(
+    SOURCE_PATH <SOURCE_PATH>
+    [OPTIONS <OPTIONS>]
+    [OPTIONS_DEBUG <OPTIONS_DEBUG>]
+    [OPTIONS_RELEASE <OPTIONS_RELEASE>]
+)
+```
+
+## Parameters:
+### SOURCE_PATH (required)
+The path to the GN project.
+
+### OPTIONS
+Options to be passed to both the debug and release targets.
+Note: Must be provided as a space-separated string.
+
+### OPTIONS_DEBUG (space-separated string)
+Options to be passed to the debug target.
+
+### OPTIONS_RELEASE (space-separated string)
+Options to be passed to the release target.
+
+## Source
+[ports/vcpkg-gn/vcpkg\_gn\_configure.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-gn/vcpkg_gn_configure.cmake)
diff --git a/docs/maintainers/ports/vcpkg-gn/vcpkg_gn_install.md b/docs/maintainers/ports/vcpkg-gn/vcpkg_gn_install.md
@@ -0,0 +1,29 @@
+# vcpkg_gn_install
+
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/ports/vcpkg-gn/vcpkg_gn_install.md).
+
+Installs a GN project.
+
+In order to build a GN project without installing, use [`vcpkg_build_ninja()`].
+
+## Usage:
+```cmake
+vcpkg_gn_install(
+     SOURCE_PATH <SOURCE_PATH>
+     [TARGETS <target>...]
+)
+```
+
+## Parameters:
+### SOURCE_PATH
+The path to the source directory
+
+### TARGETS
+Only install the specified targets.
+
+Note: includes must be handled separately
+
+[`vcpkg_build_ninja()`]: vcpkg_build_ninja.md
+
+## Source
+[ports/vcpkg-gn/vcpkg\_gn\_install.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-gn/vcpkg_gn_install.cmake)
diff --git a/docs/maintainers/pr-review-checklist.md b/docs/maintainers/pr-review-checklist.md
@@ -13,7 +13,7 @@ You can link any of these checklist items in a GitHub comment by copying the lin
 <details id="c000001">
 <summary><a href="#c000001">c000001</a>: No deprecated helper functions are used</summary>
 
-See our [Maintainer Guidelines and Policies](maintainer-guide.md#Avoid-deprecated-helper-functions) for more information.
+See our [Maintainer Guidelines and Policies](maintainer-guide.md#avoid-deprecated-helper-functions) for more information.
 
 </details>
 
@@ -36,7 +36,7 @@ See our [manifest file documentation](manifest-files.md#description) for more in
 <details id="c000004">
 <summary><a href="#c000004">c000004</a>: No unnecessary comments are present in the changeset</summary>
 
-See our [Maintainer Guidelines and Policies](maintainer-guide.md#Avoid-excessive-comments-in-portfiles) for more information.
+See our [Maintainer Guidelines and Policies](maintainer-guide.md#avoid-excessive-comments-in-portfiles) for more information.
 
 </details>
 

diff --git a/docs/regenerate.ps1 b/docs/regenerate.ps1
@@ -27,6 +27,7 @@ class CMakeDocumentation {
 
 [String[]]$cmakeScriptsPorts = @(
     'vcpkg-cmake'
+    'vcpkg-gn'
     'vcpkg-cmake-config'
     'vcpkg-cmake-get-vars'
     'vcpkg-pkgconfig-get-modules'
@@ -265,7 +266,9 @@ Get-ChildItem "$VcpkgRoot/scripts/cmake" -Filter '*.cmake' | ForEach-Object {
 $cmakeScriptsPorts | ForEach-Object {
     $portName = $_
 
-    Copy-Item "$VcpkgRoot/ports/$portName/README.md" "$PSScriptRoot/maintainers/ports/$portName.md"
+    if (Test-Path "$VcpkgRoot/ports/$portName/README.md") {
+        Copy-Item "$VcpkgRoot/ports/$portName/README.md" "$PSScriptRoot/maintainers/ports/$portName.md"
+    }
     New-Item -Path "$PSScriptRoot/maintainers/ports/$portName" -Force -ItemType 'Directory' | Out-Null
 
     $portTableOfContents[$portName] = @()

diff --git a/docs/users/buildsystems/integration.md b/docs/users/buildsystems/integration.md
@@ -6,5 +6,5 @@ vcpkg supports use from any buildsystem and has specific native integration into
 
 - [MSBuild Integration (Visual Studio)](msbuild-integration.md)
 - [CMake Integration](cmake-integration.md)
-- [Manual Integration](#manual-integration)
-- [`export` Command](#export-command)
+- [Manual Integration](manual-integration.md)
+- [`export` Command](export-command.md)
diff --git a/docs/users/buildsystems/msbuild-integration.md b/docs/users/buildsystems/msbuild-integration.md
@@ -10,7 +10,6 @@
   - [Linked NuGet Package](#linked-nuget-package)
 - [Common Configuration](#common-configuration)
 - [Manifest Mode Configuration](#manifest-mode-configuration)
-- [Classic Mode Configuration](#classic-mode-configuration)
 
 ## Integration Methods
 
@@ -60,7 +59,7 @@ More information about `Directory.Build.targets` and `Directory.Build.props` can
 
 ### Linked NuGet Package
 
-**Note: This approach is not recommended for new projects, since it makes them difficult to share with others. For a portable, self-contained NuGet package, see the [`export command`](#export-command)**
+**Note: This approach is not recommended for new projects, since it makes them difficult to share with others. For a portable, self-contained NuGet package, see the [`export command`](export-command.md)**
 
 VS projects can also be integrated through a NuGet package. This will modify the project file, so we do not recommend this approach for open source projects.
 

diff --git a/docs/users/config-environment.md b/docs/users/config-environment.md
@@ -75,19 +75,19 @@ This environment variables limits the amount of concurrency requested by underly
 
 #### VCPKG_DEFAULT_BINARY_CACHE
 
-This environment variable redirects the default location to store binary packages. See [Binary Caching](binarycaching.md#Configuration) for more details.
+This environment variable redirects the default location to store binary packages. See [Binary Caching](binarycaching.md#configuration) for more details.
 
 #### VCPKG_BINARY_SOURCES
 
-This environment variable adds or removes binary sources. See [Binary Caching](binarycaching.md#Configuration) for more details.
+This environment variable adds or removes binary sources. See [Binary Caching](binarycaching.md#configuration) for more details.
 
 #### VCPKG_NUGET_REPOSITORY
 
-This environment variable changes the metadata of produced NuGet packages. See [Binary Caching](binarycaching.md#Configuration) for more details.
+This environment variable changes the metadata of produced NuGet packages. See [Binary Caching](binarycaching.md#configuration) for more details.
 
 #### VCPKG_USE_NUGET_CACHE
 
-This environment variable allows using NuGet's cache for every nuget-based binary source. See [Binary Caching](binarycaching.md#NuGets-cache) for more details.
+This environment variable allows using NuGet's cache for every nuget-based binary source. See [Binary Caching](binarycaching.md#nuget-provider-configuration) for more details.
 
 #### X_VCPKG_ASSET_SOURCES
 

diff --git a/docs/users/manifests.md b/docs/users/manifests.md
@@ -159,6 +159,7 @@ Then, you might just ask for:
 }
 ```
 
+<a id="platform"></a>
 #### `"platform"` Field
 
 The `"platform"` field defines the platforms where the dependency should be installed - for example,

diff --git a/docs/users/mingw.md b/docs/users/mingw.md
@@ -6,10 +6,10 @@
 
 ## Table of Contents
 
- - [Mingw-w64 community triplets](#Mingw-w64-community-triplets)
- - [Using Mingw-w64 natively on Windows](#Using-Mingw-w64-natively-on-Windows)
-   - [How to avoid mixing different installations](#How-to-avoid-mixing-different-installations)
- - [Using Mingw-w64 to build Windows programs on other systems](#Using-Mingw-w64-to-build-Windows-programs-on-other-systems)
+ - [Mingw-w64 community triplets](#mingw-w64-community-triplets)
+ - [Using Mingw-w64 natively on Windows](#mingw-native)
+   - [How to avoid mixing different installations](#how-to-avoid-mixing-different-installations)
+ - [Using Mingw-w64 to build Windows programs on other systems](#mingw-cross)
 
 ## Mingw-w64 community triplets
 
@@ -36,6 +36,7 @@ Because of this, community involvement is paramount!
 - [Open issues](https://github.com/microsoft/vcpkg/issues?q=is%3Aissue+is%3Aopen+mingw)
 - [Open pull requests](https://github.com/microsoft/vcpkg/pulls?q=is%3Apr+is%3Aopen+mingw)
 
+<a id="mingw-native"></a>
 ## Using Mingw-w64 natively on Windows
 
 With [MSYS2](https://www.msys2.org/), it is possible to easily create
@@ -123,6 +124,7 @@ which create a mix of MSYS2 programs from different installations. You may
 want to set the desired `PATH` manually, or remove directories which contain
 `sh.exe`, `bash.exe`, `msys-2.0.dll` or `cygwin1.dll`.
 
+<a id="mingw-cross"></a>
 ## Using Mingw-w64 to build Windows programs on other systems
 
 You can use the vcpkg mingw community triplets with toolchains on

diff --git a/docs/users/triplets.md b/docs/users/triplets.md
@@ -8,7 +8,7 @@ In Vcpkg, we use triplets to describe an imaginary "target configuration set" fo
 
 We currently provide many triplets by default (run `vcpkg help triplet`). However, you can easily customize or add your own by copying a built-in triplet from the `triplets\` directory into a project local location. Then, use `--overlay-triplets=` (or equivalent such as [`$VCPKG_OVERLAY_TRIPLETS`](config-environment.md#vcpkg_overlay_triplets), [CMake `VCPKG_OVERLAY_TRIPLETS`](buildsystems/cmake-integration.md#vcpkg_overlay_triplets), or [MSBuild Additional Options](buildsystems/msbuild-integration.md#vcpkg-additional-install-options)) to add that directory to vcpkg. See our [overlay triplets example](../examples/overlay-triplets-linux-dynamic.md) for a more detailed walkthrough.
 
-To change the triplet used by your project away from the default, see our [Integration Document](buildsystems/integration.md#triplet-selection).
+To change the triplet used by your project, you can pass `--triplet=<triplet>` on the command line or see our [Buildsystem-Specific Documentation](buildsystems/integration.md).
 
 ## Community triplets
 
@@ -65,6 +65,7 @@ This field is optional and, if present, will be passed into the build as `CMAKE_
 
 See also the CMake documentation for `CMAKE_SYSTEM_VERSION`: https://cmake.org/cmake/help/latest/variable/CMAKE_SYSTEM_VERSION.html.
 
+<a name="VCPKG_CHAINLOAD_TOOLCHAIN_FILE"></a>
 ### VCPKG_CHAINLOAD_TOOLCHAIN_FILE
 Specifies an alternate CMake Toolchain file to use.
 

diff --git a/docs/users/versioning.md b/docs/users/versioning.md
@@ -15,7 +15,6 @@ See our guide to [getting started with versioning](../examples/versioning.gettin
   * [`version-date`](#version-date)
   * [`version-string`](#version-string)
 * [Version constraints](#version-constraints)
-* [Version files](#version-files)
 
 ## Version schemes
 Ports in vcpkg should attempt to follow the versioning conventions used by the package's authors. For that reason, when declaring a package's version the appropriate scheme should be used.
-Original file line number
+Diff line change
@@ Expand Up / @@ -159,6 +159,7 @@ Then, you might just ask for: @@
     }
     ```
+    <a id="platform"></a>
     #### `"platform"` Field
     The `"platform"` field defines the platforms where the dependency should be installed - for example,
@@ Expand Down @@