From ea270da2892849aceb1fb05cbdf08a2c67cebd77 Mon Sep 17 00:00:00 2001 From: Charlie Marsh Date: Wed, 5 Jul 2023 18:06:01 -0400 Subject: [PATCH] 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 | 2 +- .github/workflows/docs.yaml | 2 +- .gitignore | 3 +-- CONTRIBUTING.md | 2 +- README.md | 3 ++- .../integrations/analytics/fathom.html | 1 + mkdocs.template.yml | 5 +++- scripts/generate_mkdocs.py | 26 ++++++------------- 8 files changed, 19 insertions(+), 25 deletions(-) create mode 100644 docs/.overrides/partials/integrations/analytics/fathom.html diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index 9346c527a5..58969ed587 100644 --- a/.github/workflows/ci.yaml +++ b/.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 diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 27f3bacd7d..56774ee991 100644 --- a/.github/workflows/docs.yaml +++ b/.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 diff --git a/.gitignore b/.gitignore index 57a5b8f8ce..5bfce3449a 100644 --- a/.gitignore +++ b/.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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 153b43fa39..efd43b4c7e 100644 --- a/CONTRIBUTING.md +++ b/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 diff --git a/README.md b/README.md index f333191ea2..b488d61eac 100644 --- a/README.md +++ b/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 diff --git a/docs/.overrides/partials/integrations/analytics/fathom.html b/docs/.overrides/partials/integrations/analytics/fathom.html new file mode 100644 index 0000000000..340d60d816 --- /dev/null +++ b/docs/.overrides/partials/integrations/analytics/fathom.html @@ -0,0 +1 @@ + diff --git a/mkdocs.template.yml b/mkdocs.template.yml index ec7dab6ced..761c36be23 100644 --- a/mkdocs.template.yml +++ b/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 diff --git a/scripts/generate_mkdocs.py b/scripts/generate_mkdocs.py index 8d0b92b882..f6954b153a 100644 --- a/scripts/generate_mkdocs.py +++ b/scripts/generate_mkdocs.py @@ -32,10 +32,6 @@ SECTIONS: list[Section] = [ Section("Contributing", "contributing.md", generated=True), ] -FATHOM_SCRIPT: str = ( - '" -) 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)