From eaac3cae5e3aa837300c2807e43f25fb45055b27 Mon Sep 17 00:00:00 2001 From: Charlie Marsh Date: Fri, 27 Jan 2023 22:57:42 -0500 Subject: [PATCH] Add MkDocs version of README (#2287) Co-authored-by: Justin Flannery --- .github/workflows/ci.yaml | 1 + .github/workflows/docs.yaml | 35 +++++++++++++++++ .github/workflows/ruff.yaml | 22 ++++++++--- .gitignore | 1 + mkdocs.yml | 50 ++++++++++++++++++++++++ scripts/pyproject.toml | 1 + scripts/transform_readme.py | 77 +++++++++++++++++++++++++++++++++++++ 7 files changed, 181 insertions(+), 6 deletions(-) create mode 100644 .github/workflows/docs.yaml create mode 100644 mkdocs.yml create mode 100644 scripts/transform_readme.py diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index 3d15869fca..bf88c0dce9 100644 --- a/.github/workflows/ci.yaml +++ b/.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" diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml new file mode 100644 index 0000000000..268d298ade --- /dev/null +++ b/.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} diff --git a/.github/workflows/ruff.yaml b/.github/workflows/ruff.yaml index b7ba7dba27..72aeaedf82 100644 --- a/.github/workflows/ruff.yaml +++ b/.github/workflows/ruff.yaml @@ -26,8 +26,8 @@ jobs: with: python-version: ${{ env.PYTHON_VERSION }} architecture: x64 - - name: "Install Rust toolchain" - run: rustup show + - name: "Prep README.md" + 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" - run: rustup show + - name: "Prep README.md" + 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" - run: rustup show + - name: "Prep README.md" + 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: diff --git a/.gitignore b/.gitignore index 4fedb556aa..a513387eaa 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,7 @@ # Local cache .ruff_cache resources/test/cpython +docs/index.md ### # Rust.gitignore diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000000..a02ac18057 --- /dev/null +++ b/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 diff --git a/scripts/pyproject.toml b/scripts/pyproject.toml index 7b3f265041..51916374dc 100644 --- a/scripts/pyproject.toml +++ b/scripts/pyproject.toml @@ -5,6 +5,7 @@ ignore = [ "INP001", # implicit-namespace-package "PLR2004", # magic-value-comparison "S101", # assert-used + "EM" ] [tool.ruff.pydocstyle] diff --git a/scripts/transform_readme.py b/scripts/transform_readme.py new file mode 100644 index 0000000000..7a58b31848 --- /dev/null +++ b/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 = """ +

+ + + + Shows a bar chart with benchmark results. + +

+""" + +# https://github.com/pypi/warehouse/issues/11251 +PYPI = """ +

+ + Shows a bar chart with benchmark results. + +

+""" + +# https://squidfunk.github.io/mkdocs-material/reference/images/#light-and-dark-mode +MK_DOCS = """ +

+ + Shows a bar chart with benchmark results. + +

+ +

+ + Shows a bar chart with benchmark results. + +

+""" + + +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)