nordic-dev.net/nixpkgs
nordic-dev.net/nixpkgs
2
0
Fork 0
mirror of https://github.com/NixOS/nixpkgs.git synced 2024-11-22 06:53:01 +00:00
Code Issues Packages Projects Releases Wiki Activity

doc/testers: Make lycheeLinkCheck section more accessible

Browse Source 
- Explain the use case for audience who's new to the concept
- Be more explicit about what the return value "does"

(cherry picked from commit 444f8bf6eb)
This commit is contained in:
Robert Hensing 2024-03-24 22:12:50 +01:00 committed by github-actions[bot]
parent 8567fac505
commit e2a9d4f64d
1 changed files with 17 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

24
doc/build-helpers/testers.chapter.md
View File

@ -42,15 +42,11 @@ If the `moduleNames` argument is omitted, `hasPkgConfigModules` will use `meta.p
## `lycheeLinkCheck` {#tester-lycheeLinkCheck}
Check that internal hyperlinks are correct, using the [`lychee` package](https://search.nixos.org/packages?show=lychee&type=packages&query=lychee).
Check a packaged static site's links with the [`lychee` package](https://search.nixos.org/packages?show=lychee&type=packages&query=lychee).
When building the check, only an offline check is performed, so that network access is not required.
You may use Nix to reproducibly build documentation sites and other static sites. Some packages will install documentation in their `out` or `doc` outputs, or maybe you have dedicated package where you've made your static site reproducible by running a generator (like [Hugo](https://gohugo.io/), or [mdBook](https://rust-lang.github.io/mdBook/)) in a derivation.
If you'd like to run the check with network access, the returned attribute `online` can be invoked with [`nix run`](https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-run) ([experimental](https://nixos.org/manual/nix/stable/contributing/experimental-features#xp-feature-nix-command)). For example:
```shell
nix run nixpkgs#lychee.tests.ok.online
```
If you have a static site that is buildable in Nix, you can use `lycheeLinkCheck` to check that the hyperlinks in your site are correct, and do so as part of your Nix workflow and CI.
:::{.example #ex-lycheelinkcheck}
@ -64,6 +60,20 @@ testers.lycheeLinkCheck {
:::
### Return value {#tester-lycheeLinkCheck-return}
This tester produces a package that does not produce useful outputs, but only succeeds if the hyperlinks in your site are correct. The build log will list the broken links.
You may use it in two modes:
- Use the returned package directly, and the build process will check that internal hyperlinks are correct. This runs in the sandbox, so it will not check external hyperlinks, but it is quick and reliable.
- Invoke the `.online` with [`nix run`](https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-run) ([experimental](https://nixos.org/manual/nix/stable/contributing/experimental-features#xp-feature-nix-command)). This runs outside the sandbox, and check that bith internal and external hyperlinks are correct. Example:
```shell
nix run nixpkgs#lychee.tests.ok.online
```
### Parameters {#tester-lycheeLinkCheck-params}
#### `site` (required) {#tester-lycheeLinkCheck-param-site}