Split MkDocs site into multiple pages (#2296)

.github/workflows/docs.yaml

@@ -23,9 +23,8 @@ jobs:
       - name: "Copy README File"
         run: |
           python scripts/transform_readme.py --target mkdocs
-          mkdir -p docs/
+          python scripts/generate_mkdocs.py
-          cp README.md docs/index.md
+          mkdocs build --strict
-          mkdocs build
       - name: "Deploy to Cloudflare Pages"
         if: ${{ env.CF_API_TOKEN_EXISTS == 'true' }}
         uses: cloudflare/wrangler-action@2.0.0

.gitignore

@@ -1,7 +1,8 @@
 # Local cache
 .ruff_cache
 resources/test/cpython
-docs/index.md
+docs/
+mkdocs.yml
 
 ###
 # Rust.gitignore

README.md

@@ -1,3 +1,5 @@
+<!-- Begin section: Overview -->
+
 # Ruff
 
 [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v1.json)](https://github.com/charliermarsh/ruff)
@@ -106,6 +108,8 @@ developer of [Zulip](https://github.com/zulip/zulip):
 
 > This is just ridiculously fast... `ruff` is amazing.
 
+<!-- End section: Overview -->
+
 ## Table of Contents
 
 1. [Installation and Usage](#installation-and-usage)
@@ -161,6 +165,8 @@ developer of [Zulip](https://github.com/zulip/zulip):
 
 ## Installation and Usage
 
+<!-- Begin section: Installation and Usage -->
+
 ### Installation
 
 Ruff is available as [`ruff`](https://pypi.org/project/ruff/) on PyPI:
@@ -221,8 +227,12 @@ Ruff also works with [pre-commit](https://pre-commit.com):
     - id: ruff
 ```
 
+<!-- End section: Installation and Usage -->
+
 ## Configuration
 
+<!-- Begin section: Configuration -->
+
 Ruff is configurable both via `pyproject.toml` and the command line. For a full list of configurable
 options, see the [API reference](#reference).
 
@@ -426,8 +436,6 @@ line-length = 100
 All of the above rules apply equivalently to `ruff.toml` files. If Ruff detects both a `ruff.toml`
 and `pyproject.toml` file, it will defer to the `ruff.toml`.
 
-
-
 ### Python file discovery
 
 When passed a path on the command-line, Ruff will automatically discover all Python files in that
@@ -503,8 +511,12 @@ Third, Ruff can _automatically add_ `noqa` directives to all failing lines. This
 migrating a new codebase to Ruff. You can run `ruff /path/to/file.py --add-noqa` to automatically
 add `noqa` directives to all failing lines, with the appropriate rule codes.
 
+<!-- End section: Configuration -->
+
 ## Supported Rules
 
+<!-- Begin section: Rules -->
+
 Regardless of the rule's origin, Ruff re-implements every rule in Rust as a first-party feature.
 
 By default, Ruff enables Flake8's `E` and `F` rules. Ruff supports all rules from the `F` category,
@@ -1248,8 +1260,12 @@ For more, see [tryceratops](https://pypi.org/project/tryceratops/1.1.0/) on PyPI
 
 <!-- End auto-generated sections. -->
 
+<!-- End section: Rules -->
+
 ## Editor Integrations
 
+<!-- Begin section: Editor Integrations -->
+
 ### VS Code (Official)
 
 Download the [Ruff VS Code extension](https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff),
@@ -1488,8 +1504,12 @@ jobs:
         run: ruff --format=github .
 ```
 
+<!-- End section: Editor Integrations -->
+
 ## FAQ
 
+<!-- Begin section: FAQ -->
+
 ### Is Ruff compatible with Black?
 
 Yes. Ruff is compatible with [Black](https://github.com/psf/black) out-of-the-box, as long as
@@ -1534,7 +1554,7 @@ natively, including:
 - [`flake8-import-conventions`](https://github.com/joaopalmeiro/flake8-import-conventions)
 - [`flake8-logging-format`](https://pypi.org/project/flake8-logging-format/)
 - [`flake8-no-pep420`](https://pypi.org/project/flake8-no-pep420)
-- [`flake8-pie`](https://pypi.org/project/flake8-pie/) ([#1543](https://github.com/charliermarsh/ruff/issues/1543))
+- [`flake8-pie`](https://pypi.org/project/flake8-pie/)
 - [`flake8-print`](https://pypi.org/project/flake8-print/)
 - [`flake8-pytest-style`](https://pypi.org/project/flake8-pytest-style/)
 - [`flake8-quotes`](https://pypi.org/project/flake8-quotes/)
@@ -1622,7 +1642,7 @@ Today, Ruff can be used to replace Flake8 when used with any of the following pl
 - [`flake8-import-conventions`](https://github.com/joaopalmeiro/flake8-import-conventions)
 - [`flake8-logging-format`](https://pypi.org/project/flake8-logging-format/)
 - [`flake8-no-pep420`](https://pypi.org/project/flake8-no-pep420)
-- [`flake8-pie`](https://pypi.org/project/flake8-pie/) ([#1543](https://github.com/charliermarsh/ruff/issues/1543))
+- [`flake8-pie`](https://pypi.org/project/flake8-pie/)
 - [`flake8-print`](https://pypi.org/project/flake8-print/)
 - [`flake8-pytest-style`](https://pypi.org/project/flake8-pytest-style/)
 - [`flake8-quotes`](https://pypi.org/project/flake8-quotes/)
@@ -1796,6 +1816,8 @@ unfixable = ["B", "SIM", "TRY", "RUF"]
 
 If you find a case where Ruff's autofix breaks your code, please file an Issue!
 
+<!-- End section: FAQ -->
+
 ## Contributing
 
 Contributions are welcome and hugely appreciated. To get started, check out the
@@ -1932,7 +1954,9 @@ Benchmark 1: find . -type f -name "*.py" | xargs -P 0 pyupgrade --py311-plus
 
 ## Reference
 
-### Options
+<!-- Begin section: Settings -->
+
+### Top-level
 
 <!-- Sections automatically generated by `cargo dev generate-options`. -->
 <!-- Begin auto-generated options sections. -->
@@ -3693,6 +3717,8 @@ keep-runtime-typing = true
 
 <!-- End auto-generated options sections. -->
 
+<!-- End section: Settings -->
+
 ## License
 
 MIT

mkdocs.template.yml

@@ -26,8 +26,6 @@ theme:
 repo_url: https://github.com/charliermarsh/ruff
 repo_name: ruff
 site_author: charliermarsh
-nav:
-  - Home: index.md
 markdown_extensions:
   - toc:
       permalink: "#"

scripts/generate_mkdocs.py

@@ -0,0 +1,67 @@
+"""Generate an MkDocs-compatible `docs` and `mkdocs.yml` from the README.md."""
+import argparse
+import shutil
+from pathlib import Path
+
+import yaml
+
+SECTIONS: list[tuple[str, str]] = [
+    ("Overview", "index.md"),
+    ("Installation and Usage", "installation-and-usage.md"),
+    ("Configuration", "configuration.md"),
+    ("Rules", "rules.md"),
+    ("Settings", "settings.md"),
+    ("Editor Integrations", "editor-integrations.md"),
+    ("FAQ", "faq.md"),
+]
+
+
+def main() -> None:
+    """Generate an MkDocs-compatible `docs` and `mkdocs.yml`."""
+    with Path("README.md").open(encoding="utf8") as fp:
+        content = fp.read()
+
+    Path("docs").mkdir(parents=True, exist_ok=True)
+
+    # Split the README.md into sections.
+    for (title, filename) in SECTIONS:
+        with Path(f"docs/{filename}").open("w+") as f:
+            block = content.split(f"<!-- Begin section: {title} -->")
+            if len(block) != 2:
+                msg = f"Section {title} not found in README.md"
+                raise ValueError(msg)
+
+            block = block[1].split(f"<!-- End section: {title} -->")
+            if len(block) != 2:
+                msg = f"Section {title} not found in README.md"
+                raise ValueError(msg)
+
+            f.write(block[0])
+
+    # Copy the CONTRIBUTING.md.
+    shutil.copy("CONTRIBUTING.md", "docs/contributing.md")
+
+    # Add the nav section to mkdocs.yml.
+    with Path("mkdocs.template.yml").open(encoding="utf8") as fp:
+        config = yaml.safe_load(fp)
+    config["nav"] = [
+        {"Overview": "index.md"},
+        {"Installation and Usage": "installation-and-usage.md"},
+        {"Configuration": "configuration.md"},
+        {"Rules": "rules.md"},
+        {"Settings": "settings.md"},
+        {"Editor Integrations": "editor-integrations.md"},
+        {"FAQ": "faq.md"},
+        {"Contributing": "contributing.md"},
+    ]
+
+    with Path("mkdocs.yml").open("w+") as fp:
+        yaml.safe_dump(config, fp)
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(
+        description="Generate an MkDocs-compatible `docs` and `mkdocs.yml`.",
+    )
+    args = parser.parse_args()
+    main()