Minor improvements to the docs (#2371)

README.md

@@ -557,7 +557,7 @@ Running `ruff --select F401` would result in Ruff enforcing `F401`, and no other
 Running `ruff --extend-select B` would result in Ruff enforcing the `E`, `F`, and `B` rules, with
 the exception of `F401`.
 
-### Ignoring errors
+### Suppressing errors
 
 To omit a lint rule entirely, add it to the "ignore" list via [`ignore`](#ignore) or
 [`extend-ignore`](#extend-ignore), either on the command-line or in your `pyproject.toml` file.
@@ -582,7 +582,7 @@ will apply to the entire string, like so:
 ```python
 """Lorem ipsum dolor sit amet.
 
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor.
 """  # noqa: E501
 ```
 
@@ -593,17 +593,7 @@ disable enforcement across the entire file.
 For targeted exclusions across entire files (e.g., "Ignore all F841 violations in
 `/path/to/file.py`"), see the [`per-file-ignores`](#per-file-ignores) configuration setting.
 
-### "Action Comments"
+#### Automatic error suppression
-
-Ruff respects `isort`'s ["Action Comments"](https://pycqa.github.io/isort/docs/configuration/action_comments.html)
-(`# isort: skip_file`, `# isort: on`, `# isort: off`, `# isort: skip`, and `# isort: split`), which
-enable selectively enabling and disabling import sorting for blocks of code and other inline
-configuration.
-
-See the [`isort` documentation](https://pycqa.github.io/isort/docs/configuration/action_comments.html)
-for more.
-
-### Automating `noqa` Directives
 
 Ruff supports several workflows to aid in `noqa` management.
 
@@ -620,6 +610,16 @@ 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.
 
+#### Action comments
+
+Ruff respects `isort`'s [action comments](https://pycqa.github.io/isort/docs/configuration/action_comments.html)
+(`# isort: skip_file`, `# isort: on`, `# isort: off`, `# isort: skip`, and `# isort: split`), which
+enable selectively enabling and disabling import sorting for blocks of code and other inline
+configuration.
+
+See the [`isort` documentation](https://pycqa.github.io/isort/docs/configuration/action_comments.html)
+for more.
+
 <!-- End section: Configuration -->
 
 ## Supported Rules

scripts/generate_mkdocs.py

@@ -15,12 +15,22 @@ SECTIONS: list[tuple[str, str]] = [
     ("FAQ", "faq.md"),
 ]
 
+DOCUMENTATION_LINK: str = (
+    "This README is also available as [documentation](https://beta.ruff.rs/docs/)."
+)
+
 
 def main() -> None:
     """Generate an MkDocs-compatible `docs` and `mkdocs.yml`."""
     with Path("README.md").open(encoding="utf8") as fp:
         content = fp.read()
 
+    # Remove the documentation link, since we're _in_ the docs.
+    if DOCUMENTATION_LINK not in content:
+        msg = "README.md is not in the expected format."
+        raise ValueError(msg)
+    content = content.replace(DOCUMENTATION_LINK, "")
+
     Path("docs").mkdir(parents=True, exist_ok=True)
 
     # Split the README.md into sections.