Add MkDocs version of README (#2287)

Co-authored-by: Justin Flannery <juftin@juftin.com>

.github/workflows/ci.yaml

@@ -112,6 +112,7 @@ jobs:
           python-version: "3.11"
       - run: pip install maturin
       - run: maturin build -b bin
+      - run: python scripts/transform_readme.py --target pypi
 
   typos:
     name: "spell check"

.github/workflows/docs.yaml

@@ -0,0 +1,35 @@
+name: mkdocs
+
+on:
+  push:
+    paths:
+      - README.md
+      - mkdocs.yml
+      - .github/workflows/docs.yaml
+    branches: [ main ]
+  pull_request:
+
+jobs:
+  mkdocs:
+    runs-on: ubuntu-latest
+    env:
+       CF_API_TOKEN_EXISTS: ${{ secrets.CF_API_TOKEN != '' }}
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+      - name: "Install dependencies"
+        run: |
+          pip install "mkdocs~=1.4.2" "mkdocs-material~=9.0.6"
+      - name: "Copy README File"
+        run: |
+          python scripts/transform_readme.py --target mkdocs
+          mkdir -p docs/
+          cp README.md docs/index.md
+          mkdocs build
+      - name: "Deploy to Cloudflare Pages"
+        if: ${{ env.CF_API_TOKEN_EXISTS == 'true' }}
+        uses: cloudflare/wrangler-action@2.0.0
+        with:
+          apiToken: ${{ secrets.CF_API_TOKEN }}
+          accountId: ${{ secrets.CF_ACCOUNT_ID }}
+          command: pages publish site --project-name=ruff-docs --branch ${GITHUB_HEAD_REF} --commit-hash ${GITHUB_SHA}

.github/workflows/ruff.yaml

@@ -26,8 +26,8 @@ jobs:
         with:
           python-version: ${{ env.PYTHON_VERSION }}
           architecture: x64
-      - name: "Install Rust toolchain"
+      - name: "Prep README.md"
-        run: rustup show
+        run: python scripts/transform_readme.py --target pypi
       - name: "Build wheels - x86_64"
         uses: messense/maturin-action@v1
         with:
@@ -49,8 +49,8 @@ jobs:
         with:
           python-version: ${{ env.PYTHON_VERSION }}
           architecture: x64
-      - name: "Install Rust toolchain"
+      - name: "Prep README.md"
-        run: rustup show
+        run: python scripts/transform_readme.py --target pypi
       - name: "Build wheels - universal2"
         uses: messense/maturin-action@v1
         with:
@@ -75,8 +75,8 @@ jobs:
         with:
           python-version: ${{ env.PYTHON_VERSION }}
           architecture: ${{ matrix.target }}
-      - name: "Install Rust toolchain"
+      - name: "Prep README.md"
-        run: rustup show
+        run: python scripts/transform_readme.py --target pypi
       - name: "Build wheels"
         uses: messense/maturin-action@v1
         with:
@@ -103,6 +103,8 @@ jobs:
         with:
           python-version: ${{ env.PYTHON_VERSION }}
           architecture: x64
+      - name: "Prep README.md"
+        run: python scripts/transform_readme.py --target pypi
       - name: "Build wheels"
         uses: messense/maturin-action@v1
         with:
@@ -129,6 +131,8 @@ jobs:
       - uses: actions/setup-python@v4
         with:
           python-version: ${{ env.PYTHON_VERSION }}
+      - name: "Prep README.md"
+        run: python scripts/transform_readme.py --target pypi
       - name: "Build wheels"
         uses: messense/maturin-action@v1
         with:
@@ -167,6 +171,8 @@ jobs:
         with:
           python-version: ${{ env.PYTHON_VERSION }}
           architecture: x64
+      - name: "Prep README.md"
+        run: python scripts/transform_readme.py --target pypi
       - name: "Build wheels"
         uses: messense/maturin-action@v1
         with:
@@ -202,6 +208,8 @@ jobs:
       - uses: actions/setup-python@v4
         with:
           python-version: ${{ env.PYTHON_VERSION }}
+      - name: "Prep README.md"
+        run: python scripts/transform_readme.py --target pypi
       - name: "Build wheels"
         uses: messense/maturin-action@v1
         with:
@@ -242,6 +250,8 @@ jobs:
       - uses: actions/setup-python@v4
         with:
           python-version: pypy${{ matrix.python-version }}
+      - name: "Prep README.md"
+        run: python scripts/transform_readme.py --target pypi
       - name: "Build wheels"
         uses: messense/maturin-action@v1
         with:

.gitignore

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

mkdocs.yml

@@ -0,0 +1,50 @@
+site_name: Ruff
+theme:
+  name: material
+  features:
+    - navigation.instant
+    - navigation.tracking
+    - content.code.annotate
+    - toc.integrate
+    - toc.follow
+    - navigation.path
+    - navigation.top
+    - content.code.copy
+  palette:
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: indigo
+      toggle:
+        icon: material/weather-sunny
+        name: Switch to dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: indigo
+      toggle:
+        icon: material/weather-night
+        name: Switch to light mode
+repo_url: https://github.com/charliermarsh/ruff
+repo_name: ruff
+site_author: charliermarsh
+remote_branch: gh-pages
+nav:
+  - Ruff: index.md
+markdown_extensions:
+  - toc:
+      permalink: "#"
+  - pymdownx.snippets:
+  - pymdownx.magiclink:
+  - attr_list:
+  - md_in_html:
+  - pymdownx.highlight:
+      anchor_linenums: true
+  - pymdownx.inlinehilite:
+  - pymdownx.superfences:
+  - markdown.extensions.attr_list:
+  - pymdownx.keys:
+  - pymdownx.tasklist:
+      custom_checkbox: true
+  - pymdownx.highlight:
+      anchor_linenums: true
+plugins:
+  - search

scripts/pyproject.toml

@@ -5,6 +5,7 @@ ignore = [
   "INP001",  # implicit-namespace-package
   "PLR2004", # magic-value-comparison
   "S101",    # assert-used
+  "EM"
 ]
 
 [tool.ruff.pydocstyle]

scripts/transform_readme.py

@@ -0,0 +1,77 @@
+"""Transform the README.md to support a specific deployment target.
+
+By default, we assume that our README.md will be rendered on GitHub. However, different
+targets have different strategies for rendering light- and dark-mode images. This script
+adjusts the images in the README.md to support the given target.
+"""
+import argparse
+from pathlib import Path
+
+# https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#specifying-the-theme-an-image-is-shown-to
+GITHUB = """
+<p align="center">
+  <picture align="center">
+    <source media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/1309177/212613422-7faaf278-706b-4294-ad92-236ffcab3430.svg">
+    <source media="(prefers-color-scheme: light)" srcset="https://user-images.githubusercontent.com/1309177/212613257-5f4bca12-6d6b-4c79-9bac-51a4c6d08928.svg">
+    <img alt="Shows a bar chart with benchmark results." src="https://user-images.githubusercontent.com/1309177/212613257-5f4bca12-6d6b-4c79-9bac-51a4c6d08928.svg">
+  </picture>
+</p>
+"""
+
+# https://github.com/pypi/warehouse/issues/11251
+PYPI = """
+<p align="center">
+  <picture align="center">
+    <img alt="Shows a bar chart with benchmark results." src="https://user-images.githubusercontent.com/1309177/212613257-5f4bca12-6d6b-4c79-9bac-51a4c6d08928.svg">
+  </picture>
+</p>
+"""
+
+# https://squidfunk.github.io/mkdocs-material/reference/images/#light-and-dark-mode
+MK_DOCS = """
+<p align="center">
+  <picture align="center">
+    <img alt="Shows a bar chart with benchmark results." src="https://user-images.githubusercontent.com/1309177/212613257-5f4bca12-6d6b-4c79-9bac-51a4c6d08928.svg#only-light">
+  </picture>
+</p>
+
+<p align="center">
+  <picture align="center">
+    <img alt="Shows a bar chart with benchmark results." src="https://user-images.githubusercontent.com/1309177/212613422-7faaf278-706b-4294-ad92-236ffcab3430.svg#only-dark">
+  </picture>
+</p>
+"""
+
+
+def main(target: str) -> None:
+    """Modify the README.md to support the given target."""
+    with Path("README.md").open(encoding="utf8") as fp:
+        content = fp.read()
+        if GITHUB not in content:
+            msg = "README.md is not in the expected format."
+            raise ValueError(msg)
+
+    if target == "pypi":
+        with Path("README.md").open("w", encoding="utf8") as fp:
+            fp.write(content.replace(GITHUB, PYPI))
+    elif target == "mkdocs":
+        with Path("README.md").open("w", encoding="utf8") as fp:
+            fp.write(content.replace(GITHUB, MK_DOCS))
+    else:
+        msg = f"Unknown target: {target}"
+        raise ValueError(msg)
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(
+        description="Modify the README.md to support a specific deployment target.",
+    )
+    parser.add_argument(
+        "--target",
+        type=str,
+        required=True,
+        choices=("pypi", "mkdocs"),
+    )
+    args = parser.parse_args()
+
+    main(target=args.target)