From 071e3fd196b01e970def9a0ca720359ac472125b Mon Sep 17 00:00:00 2001 From: Charlie Marsh Date: Sat, 28 Jan 2023 08:31:16 -0500 Subject: [PATCH] Split MkDocs site into multiple pages (#2296) --- .github/workflows/docs.yaml | 5 +-- .gitignore | 3 +- README.md | 36 ++++++++++++++--- mkdocs.yml => mkdocs.template.yml | 2 - scripts/generate_mkdocs.py | 67 +++++++++++++++++++++++++++++++ 5 files changed, 102 insertions(+), 11 deletions(-) rename mkdocs.yml => mkdocs.template.yml (97%) create mode 100644 scripts/generate_mkdocs.py diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 268d298ade..62471265fb 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -23,9 +23,8 @@ jobs: - name: "Copy README File" run: | python scripts/transform_readme.py --target mkdocs - mkdir -p docs/ - cp README.md docs/index.md - mkdocs build + python scripts/generate_mkdocs.py + mkdocs build --strict - 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 a513387eaa..ffcc7718ed 100644 --- a/.gitignore +++ b/.gitignore @@ -1,7 +1,8 @@ # Local cache .ruff_cache resources/test/cpython -docs/index.md +docs/ +mkdocs.yml ### # Rust.gitignore diff --git a/README.md b/README.md index 2f6982cfe4..f246c2228a 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,5 @@ + + # 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. + + ## 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 + + ### 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 ``` + + ## 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. + + ## Supported 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 + + ## 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 . ``` + + ## 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! + + ## 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 + + +### Top-level @@ -3693,6 +3717,8 @@ keep-runtime-typing = true + + ## License MIT diff --git a/mkdocs.yml b/mkdocs.template.yml similarity index 97% rename from mkdocs.yml rename to mkdocs.template.yml index 4321e9078d..c15e423563 100644 --- a/mkdocs.yml +++ b/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: "#" diff --git a/scripts/generate_mkdocs.py b/scripts/generate_mkdocs.py new file mode 100644 index 0000000000..76ded153ee --- /dev/null +++ b/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"") + if len(block) != 2: + msg = f"Section {title} not found in README.md" + raise ValueError(msg) + + block = block[1].split(f"") + 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()