From 85be33d719d4bd432783a5259920db47285ab6ad Mon Sep 17 00:00:00 2001
From: Mathieu Kniewallner <mathieu.kniewallner@gmail.com>
Date: Thu, 15 Aug 2024 02:27:22 +0200
Subject: [PATCH] docs: use stricter validation options (#6096)

## Summary

`mkdocs` supports [validation rules for
links](https://www.mkdocs.org/user-guide/configuration/#validation),
which can be tightened to report more issues than the default
configuration. I used the recommended "maximal strictness" configuration
from the documentation.

Adding the `anchors` rule helped spot 4 errors:
```console
WARNING -  Doc file 'guides/install-python.md' contains a link '../concepts/python-versions.md#python-distributions', but the doc 'concepts/python-versions.md' does not contain an anchor '#python-distributions'.
WARNING -  Doc file 'guides/install-python.md' contains a link '../concepts/python-versions.md#discovery-order', but the doc 'concepts/python-versions.md' does not contain an anchor '#discovery-order'.
WARNING -  Doc file 'guides/projects.md' contains a link '../concepts/projects.md#lock-file', but the doc 'concepts/projects.md' does not contain an anchor '#lock-file'.
WARNING -  Doc file 'pip/environments.md' contains a link '../concepts/python-versions.md#discovery-order', but the doc 'concepts/python-versions.md' does not contain an anchor '#discovery-order'.
```

## Test Plan

Local run of the documentation + `mkdocs build --strict`.
---
 docs/guides/install-python.md | 7 ++++---
 docs/guides/projects.md       | 2 +-
 docs/pip/environments.md      | 4 ++--
 mkdocs.template.yml           | 5 +++++
 4 files changed, 12 insertions(+), 6 deletions(-)

diff --git a/docs/guides/install-python.md b/docs/guides/install-python.md
index 2849722e0..2ea6e198c 100644
--- a/docs/guides/install-python.md
+++ b/docs/guides/install-python.md
@@ -23,7 +23,7 @@ system. If you've previously installed Python with uv, a new version will not be
 
 !!! note
 
-    Python does not publish official distributable binaries. As such, uv uses third-party distributions from the [`python-build-standalone`](https://github.com/indygreg/python-build-standalone) project. The project is partially maintained by the uv maintainers and is used by other prominent Python projects (e.g., [Rye](https://github.com/astral-sh/rye), [Bazel](https://github.com/bazelbuild/rules_python)). See the [Python distributions](../concepts/python-versions.md#python-distributions) documentation for more details.
+    Python does not publish official distributable binaries. As such, uv uses third-party distributions from the [`python-build-standalone`](https://github.com/indygreg/python-build-standalone) project. The project is partially maintained by the uv maintainers and is used by other prominent Python projects (e.g., [Rye](https://github.com/astral-sh/rye), [Bazel](https://github.com/bazelbuild/rules_python)). See the [Python distributions](../concepts/python-versions.md#managed-python-distributions) documentation for more details.
 
 <!-- TODO(zanieb): Restore when Python shim management is added
 Note that when an automatic Python installation occurs, the `python` command will not be added to the shell. Use `uv python install-shim` to ensure the `python` shim is installed.
@@ -112,8 +112,9 @@ Note that when an automatic Python installation occurs, the `python` command wil
 
 uv will use existing Python installations if present on your system. There is no configuration
 necessary for this behavior: uv will use the system Python if it satisfies the requirements of the
-command invocation. See the [Python discovery](../concepts/python-versions.md#discovery-order)
-documentation for details.
+command invocation. See the
+[Python discovery](../concepts/python-versions.md#discovery-of-python-versions) documentation for
+details.
 
 To force uv to use the system Python, provide the `--python-preference only-system` option. See the
 [Python version preference](../concepts/python-versions.md#adjusting-python-version-preferences)
diff --git a/docs/guides/projects.md b/docs/guides/projects.md
index c49cfbb87..a2e0ba72e 100644
--- a/docs/guides/projects.md
+++ b/docs/guides/projects.md
@@ -92,7 +92,7 @@ reproducible installations across machines.
 
 `uv.lock` is a human-readable TOML file but is managed by uv and should not be edited manually.
 
-See the [lockfile](../concepts/projects.md#lock-file) documentation for more details.
+See the [lockfile](../concepts/projects.md#lockfile) documentation for more details.
 
 ## Managing dependencies
 
diff --git a/docs/pip/environments.md b/docs/pip/environments.md
index e6c21bfb7..890e9af24 100644
--- a/docs/pip/environments.md
+++ b/docs/pip/environments.md
@@ -111,5 +111,5 @@ If the `--system` flag is included, uv will skip virtual environments search for
 version. Similarly, when running a command that does not mutate the environment such as
 `uv pip compile`, uv does not _require_ a virtual environment — however, a Python interpreter is
 still required. See the documentation on
-[Python discovery](../concepts/python-versions.md#discovery-order) for details on the discovery of
-installed Python versions.
+[Python discovery](../concepts/python-versions.md#discovery-of-python-versions) for details on the
+discovery of installed Python versions.
diff --git a/mkdocs.template.yml b/mkdocs.template.yml
index 1ccd799cf..0b15693b8 100644
--- a/mkdocs.template.yml
+++ b/mkdocs.template.yml
@@ -127,3 +127,8 @@ nav:
       - Resolver: reference/resolver-internals.md
       - Versioning: reference/versioning.md
       - Platform support: reference/platforms.md
+validation:
+  omitted_files: warn
+  absolute_links: warn
+  unrecognized_links: warn
+  anchors: warn