Move some MkDocs responsibilities around (#5542)

## Summary

Note that I've also changed from `mkdocs serve` to `mkdocs serve -f
mkdocs.generated.yml` to be clearer that this is a generated file.

.github/workflows/ci.yaml

@@ -271,4 +271,4 @@ jobs:
       - name: "Check docs formatting"
         run: python scripts/check_docs_formatted.py
       - name: "Build docs"
-        run: mkdocs build --strict
+        run: mkdocs build --strict -f mkdocs.generated.yml

.github/workflows/docs.yaml

@@ -26,7 +26,7 @@ jobs:
         run: |
           python scripts/transform_readme.py --target mkdocs
           python scripts/generate_mkdocs.py
-          mkdocs build --strict
+          mkdocs build --strict -f mkdocs.generated.yml
       - name: "Deploy to Cloudflare Pages"
         if: ${{ env.CF_API_TOKEN_EXISTS == 'true' }}
         uses: cloudflare/wrangler-action@2.0.0

.gitignore

@@ -1,8 +1,7 @@
 # Benchmarking cpython (CONTRIBUTING.md)
 crates/ruff/resources/test/cpython
 # generate_mkdocs.py
-mkdocs.yml
-.overrides
+mkdocs.generated.yml
 # check_ecosystem.py
 ruff-old
 github_search*.jsonl

CONTRIBUTING.md

@@ -256,7 +256,7 @@ To preview any changes to the documentation locally:
 1. Run the development server with:
 
    ```shell
-   mkdocs serve
+   mkdocs serve -f mkdocs.generated.yml
    ```
 
 The documentation should then be available locally at

README.md

@@ -34,7 +34,8 @@ An extremely fast Python linter, written in Rust.
 - ⚖️ [Near-parity](https://beta.ruff.rs/docs/faq/#how-does-ruff-compare-to-flake8) with the
   built-in Flake8 rule set
 - 🔌 Native re-implementations of dozens of Flake8 plugins, like flake8-bugbear
-- ⌨️ First-party editor integrations for [VS Code](https://github.com/astral-sh/ruff-vscode) and [more](https://github.com/astral-sh/ruff-lsp)
+- ⌨️ First-party [editor integrations](https://beta.ruff.rs/docs/editor-integrations/) for
+  [VS Code](https://github.com/astral-sh/ruff-vscode) and [more](https://github.com/astral-sh/ruff-lsp)
 - 🌎 Monorepo-friendly, with [hierarchical and cascading configuration](https://beta.ruff.rs/docs/configuration/#pyprojecttoml-discovery)
 
 Ruff aims to be orders of magnitude faster than alternative tools while integrating more

docs/.overrides/partials/integrations/analytics/fathom.html

@@ -0,0 +1 @@
+<script src="https://cdn.usefathom.com/script.js" data-site="DUAEBFLB" defer></script>

mkdocs.template.yml

@@ -23,7 +23,7 @@ theme:
       toggle:
         icon: material/weather-night
         name: Switch to light mode
-  custom_dir: .overrides
+  custom_dir: docs/.overrides
 repo_url: https://github.com/astral-sh/ruff
 repo_name: ruff
 site_author: charliermarsh
@@ -50,3 +50,6 @@ plugins:
   - search
 extra_css:
   - stylesheets/extra.css
+extra:
+  analytics:
+    provider: fathom

scripts/generate_mkdocs.py

@@ -32,10 +32,6 @@ SECTIONS: list[Section] = [
     Section("Contributing", "contributing.md", generated=True),
 ]
 
-FATHOM_SCRIPT: str = (
-    '<script src="https://cdn.usefathom.com/script.js" data-site="DUAEBFLB" defer>'
-    "</script>"
-)
 
 LINK_REWRITES: dict[str, str] = {
     "https://beta.ruff.rs/docs/": "index.md",
@@ -45,7 +41,6 @@ LINK_REWRITES: dict[str, str] = {
     ),
     "https://beta.ruff.rs/docs/contributing/": "contributing.md",
     "https://beta.ruff.rs/docs/editor-integrations/": "editor-integrations.md",
-    "https://beta.ruff.rs/docs/faq/": "faq.md",
     "https://beta.ruff.rs/docs/faq/#how-does-ruff-compare-to-flake8": (
         "faq.md#how-does-ruff-compare-to-flake8"
     ),
@@ -53,7 +48,6 @@ LINK_REWRITES: dict[str, str] = {
     "https://beta.ruff.rs/docs/rules/": "rules.md",
     "https://beta.ruff.rs/docs/rules/#error-e": "rules.md#error-e",
     "https://beta.ruff.rs/docs/settings/": "settings.md",
-    "https://beta.ruff.rs/docs/usage/": "usage.md",
 }
 
 
@@ -92,7 +86,13 @@ def main() -> None:
 
     # Rewrite links to the documentation.
     for src, dst in LINK_REWRITES.items():
-        content = content.replace(f"({src})", f"({dst})")
+        before = content
+        after = content.replace(f"({src})", f"({dst})")
+        if before == after:
+            msg = f"Unexpected link rewrite in README.md: {src}"
+            raise ValueError(msg)
+        content = after
+
     if m := re.search(r"\(https://beta.ruff.rs/docs/.*\)", content):
         msg = f"Unexpected absolute link to documentation: {m.group(0)}"
         raise ValueError(msg)
@@ -140,18 +140,8 @@ def main() -> None:
     with Path("mkdocs.template.yml").open(encoding="utf8") as fp:
         config = yaml.safe_load(fp)
     config["nav"] = [{section.title: section.filename} for section in SECTIONS]
-    config["extra"] = {"analytics": {"provider": "fathom"}}
 
-    Path(".overrides/partials/integrations/analytics").mkdir(
-        parents=True,
-        exist_ok=True,
-    )
-    with Path(".overrides/partials/integrations/analytics/fathom.html").open(
-        "w+",
-    ) as fp:
-        fp.write(FATHOM_SCRIPT)
-
-    with Path("mkdocs.yml").open("w+") as fp:
+    with Path("mkdocs.generated.yml").open("w+") as fp:
         yaml.safe_dump(config, fp)