Skip to content

Commit

Permalink
[docs] Fix broken links. Add docs validation pipeline.
Browse files Browse the repository at this point in the history
  • Loading branch information
ras0219-msft authored May 18, 2022
1 parent 8639e65 commit 40a97dd
Show file tree
Hide file tree
Showing 16 changed files with 153 additions and 23 deletions.
54 changes: 54 additions & 0 deletions .github/workflows/validateDocs.yml
Original file line number Diff line number Diff line change
@@ -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: '5384646ab8120d749ff258680f3a7fc5a29caaef'
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
5 changes: 0 additions & 5 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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/)
Expand Down
4 changes: 2 additions & 2 deletions docs/about/faq.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down
5 changes: 5 additions & 0 deletions docs/maintainers/portfile-functions.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
12 changes: 12 additions & 0 deletions docs/maintainers/ports/vcpkg-gn.md
Original file line number Diff line number Diff line change
@@ -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()
```
32 changes: 32 additions & 0 deletions docs/maintainers/ports/vcpkg-gn/vcpkg_gn_configure.md
Original file line number Diff line number Diff line change
@@ -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)
29 changes: 29 additions & 0 deletions docs/maintainers/ports/vcpkg-gn/vcpkg_gn_install.md
Original file line number Diff line number Diff line change
@@ -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)
4 changes: 2 additions & 2 deletions docs/maintainers/pr-review-checklist.md
Original file line number Diff line number Diff line change
Expand Up @@ -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>

Expand All @@ -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>

Expand Down
1 change: 1 addition & 0 deletions docs/regenerate.ps1
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@ class CMakeDocumentation {

[String[]]$cmakeScriptsPorts = @(
'vcpkg-cmake'
'vcpkg-gn'
'vcpkg-cmake-config'
'vcpkg-cmake-get-vars'
'vcpkg-pkgconfig-get-modules'
Expand Down
4 changes: 2 additions & 2 deletions docs/users/buildsystems/integration.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
3 changes: 1 addition & 2 deletions docs/users/buildsystems/msbuild-integration.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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.

Expand Down
8 changes: 4 additions & 4 deletions docs/users/config-environment.md
Original file line number Diff line number Diff line change
Expand Up @@ -77,19 +77,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

Expand Down
1 change: 1 addition & 0 deletions docs/users/manifests.md
Original file line number Diff 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
10 changes: 6 additions & 4 deletions docs/users/mingw.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down
3 changes: 2 additions & 1 deletion docs/users/triplets.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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.

Expand Down
1 change: 0 additions & 1 deletion docs/users/versioning.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down

0 comments on commit 40a97dd

Please sign in to comment.