Split up some docs sections (#3154)

README.md

@@ -119,7 +119,7 @@ pip install ruff
 ```
 
 You can also install Ruff via [Homebrew](https://formulae.brew.sh/formula/ruff), [Conda](https://anaconda.org/conda-forge/ruff),
-and with [a variety of other package managers](https://beta.ruff.rs/docs/installation-and-usage/).
+and with [a variety of other package managers](https://beta.ruff.rs/docs/installation/).
 
 ### Usage
 
@@ -143,7 +143,7 @@ Ruff can also be used as a [pre-commit](https://pre-commit.com) hook:
 ```
 
 Ruff can also be used as a [VS Code extension](https://github.com/charliermarsh/ruff-vscode) or
-with other editors through the [Ruff LSP](https://github.com/charliermarsh/ruff-lsp).
+alongside any other editor through the [Ruff LSP](https://github.com/charliermarsh/ruff-lsp).
 
 ### Configuration
 

docs/.gitignore

@@ -1,7 +1,8 @@
 *
 !assets
 !requirements.txt
+!configuration.md
 !editor-integrations.md
 !faq.md
-!configuration.md
+!installation.md
-!installation-and-usage.md
+!usage.md

docs/configuration.md

@@ -1,11 +1,13 @@
+# Configuring Ruff
+
 Ruff can be configured via a `pyproject.toml` file, a `ruff.toml` file, or through the command line.
 
 For a complete enumeration of the available configuration options, see
 [_Settings_](/docs/settings/).
 
-### Configure via `pyproject.toml`
+### Via `pyproject.toml`
 
-If left unspecified, the default configuration is equivalent to:
+If left unspecified, Ruff's default configuration is equivalent to:
 
 ```toml
 [tool.ruff]
@@ -89,16 +91,18 @@ select = ["E", "F", "Q"]
 docstring-quotes = "double"
 ```
 
+For a complete enumeration of the available configuration options, see
+[_Settings_](/docs/settings/).
+
 Ruff mirrors Flake8's rule code system, in which each rule code consists of a one-to-three letter
 prefix, followed by three digits (e.g., `F401`). The prefix indicates that "source" of the rule
 (e.g., `F` for Pyflakes, `E` for pycodestyle, `ANN` for flake8-annotations). The set of enabled
-rules is determined by the `select` and `ignore` options, which support both the full code (e.g.,
+rules is determined by the `select` and `ignore` options, which accept either the full code (e.g.,
-`F401`) and the prefix (e.g., `F`).
+`F401`) or the prefix (e.g., `F`).
 
-As a special-case, Ruff also supports the `ALL` code, which enables all rules. Note that some of the
+As a special-case, Ruff also supports the `ALL` code, which enables all rules. Note that some
 pydocstyle rules conflict (e.g., `D203` and `D211`) as they represent alternative docstring
-formats. Enabling `ALL` without further configuration may result in suboptimal behavior, especially
+formats. Ruff will automatically disable any conflicting rules when `ALL` is enabled.
-for the pydocstyle plugin.
 
 If you're wondering how to configure Ruff, here are some **recommended guidelines**:
 
@@ -111,11 +115,13 @@ If you're wondering how to configure Ruff, here are some **recommended guideline
 * By default, Ruff's autofix is aggressive. If you find that it's too aggressive for your liking,
   consider turning off autofix for specific rules or categories (see the [_FAQ_](/docs/faq/#ruff-tried-to-fix-something-but-it-broke-my-code-what-should-i-do)).
 
-### Configure via `ruff.toml`
+### Via `ruff.toml`
 
 As an alternative to `pyproject.toml`, Ruff will also respect a `ruff.toml` file, which implements
-an equivalent schema (though the `[tool.ruff]` hierarchy can be omitted). For example, the
+an equivalent schema (though the `[tool.ruff]` hierarchy can be omitted).
-`pyproject.toml` described above would be represented via the following `ruff.toml`:
+
+For example, the `pyproject.toml` described above would be represented via the following
+`ruff.toml`:
 
 ```toml
 # Enable flake8-bugbear (`B`) rules.
@@ -138,8 +144,8 @@ For a complete enumeration of the available configuration options, see
 
 ### Command-line interface
 
-Some configuration settings can be provided via the command-line, such as those related to
+Some configuration options can be provided via the command-line, such as those related to rule
-rule enablement and disablement, file discovery, logging level, and more:
+enablement and disablement, file discovery, logging level, and more:
 
 ```shell
 ruff check path/to/code/ --select F401 --select F403 --quiet
@@ -265,7 +271,7 @@ Log levels:
 Similar to [ESLint](https://eslint.org/docs/latest/user-guide/configuring/configuration-files#cascading-and-hierarchy),
 Ruff supports hierarchical configuration, such that the "closest" `pyproject.toml` file in the
 directory hierarchy is used for every individual file, with all paths in the `pyproject.toml` file
-(e.g., `exclude` globs, `src` paths) being resolved relative to the directory containing the
+(e.g., `exclude` globs, `src` paths) being resolved relative to the directory containing that
 `pyproject.toml` file.
 
 There are a few exceptions to these rules:
@@ -312,7 +318,7 @@ By default, Ruff will also skip any files that are omitted via `.ignore`, `.giti
 Files that are passed to `ruff` directly are always linted, regardless of the above criteria.
 For example, `ruff check /path/to/excluded/file.py` will always lint `file.py`.
 
-### Rule resolution
+### Rule selection
 
 The set of enabled rules is controlled via the [`select`](/docs/settings#select) and
 [`ignore`](/docs/settings#ignore) settings, along with the
@@ -341,7 +347,7 @@ Running `ruff check --select F401` would result in Ruff enforcing `F401`, and no
 Running `ruff check --extend-select B` would result in Ruff enforcing the `E`, `F`, and `B` rules,
 with the exception of `F401`.
 
-### Suppressing errors
+### Error suppression
 
 To omit a lint rule entirely, add it to the "ignore" list via [`ignore`](/docs/settings#ignore)
 or [`extend-ignore`](/docs/settings#extend-ignore), either on the command-line
@@ -391,7 +397,7 @@ setting, which enables the same functionality via a `pyproject.toml` file.
 Note that Ruff will also respect Flake8's `# flake8: noqa` directive, and will treat it as
 equivalent to `# ruff: noqa`.
 
-#### Automatic error suppression
+#### Automatic `noqa` management
 
 Ruff supports several workflows to aid in `noqa` management.
 

docs/installation-and-usage.md

@@ -1,76 +0,0 @@
-### Installation
-
-Ruff is available as [`ruff`](https://pypi.org/project/ruff/) on PyPI:
-
-```shell
-pip install ruff
-```
-
-For **macOS Homebrew** and **Linuxbrew** users, Ruff is also available as [`ruff`](https://formulae.brew.sh/formula/ruff) on Homebrew:
-
-```shell
-brew install ruff
-```
-
-For **Conda** users, Ruff is also available as [`ruff`](https://anaconda.org/conda-forge/ruff) on
-`conda-forge`:
-
-```shell
-conda install -c conda-forge ruff
-```
-
-For **Arch Linux** users, Ruff is also available as [`ruff`](https://archlinux.org/packages/community/x86_64/ruff/)
-on the official repositories:
-
-```shell
-pacman -S ruff
-```
-
-For **Alpine** users, Ruff is also available as [`ruff`](https://pkgs.alpinelinux.org/package/edge/testing/x86_64/ruff)
-on the testing repositories:
-
-```shell
-apk add ruff
-```
-
-[![Packaging status](https://repology.org/badge/vertical-allrepos/ruff-python-linter.svg?exclude_unsupported=1)](https://repology.org/project/ruff-python-linter/versions)
-
-### Usage
-
-To run Ruff, try any of the following:
-
-```shell
-ruff check .                        # Lint all files in the current directory (and any subdirectories)
-ruff check path/to/code/            # Lint all files in `/path/to/code` (and any subdirectories)
-ruff check path/to/code/*.py        # Lint all `.py` files in `/path/to/code`
-ruff check path/to/code/to/file.py  # Lint `file.py`
-```
-
-You can run Ruff in `--watch` mode to automatically re-run on-change:
-
-```shell
-ruff check path/to/code/ --watch
-```
-
-Ruff also works with [pre-commit](https://pre-commit.com):
-
-```yaml
-- repo: https://github.com/charliermarsh/ruff-pre-commit
-  # Ruff version.
-  rev: 'v0.0.252'
-  hooks:
-    - id: ruff
-```
-
-Or, to enable autofix:
-
-```yaml
-- repo: https://github.com/charliermarsh/ruff-pre-commit
-  # Ruff version.
-  rev: 'v0.0.252'
-  hooks:
-    - id: ruff
-      args: [--fix, --exit-non-zero-on-fix]
-```
-
-Note that Ruff's pre-commit hook should run before Black, isort, and other formatting tools.

docs/installation.md

@@ -0,0 +1,36 @@
+# Installing Ruff
+
+Ruff is available as [`ruff`](https://pypi.org/project/ruff/) on PyPI:
+
+```shell
+pip install ruff
+```
+
+For **macOS Homebrew** and **Linuxbrew** users, Ruff is also available as [`ruff`](https://formulae.brew.sh/formula/ruff) on Homebrew:
+
+```shell
+brew install ruff
+```
+
+For **Conda** users, Ruff is also available as [`ruff`](https://anaconda.org/conda-forge/ruff) on
+`conda-forge`:
+
+```shell
+conda install -c conda-forge ruff
+```
+
+For **Arch Linux** users, Ruff is also available as [`ruff`](https://archlinux.org/packages/community/x86_64/ruff/)
+on the official repositories:
+
+```shell
+pacman -S ruff
+```
+
+For **Alpine** users, Ruff is also available as [`ruff`](https://pkgs.alpinelinux.org/package/edge/testing/x86_64/ruff)
+on the testing repositories:
+
+```shell
+apk add ruff
+```
+
+[![Packaging status](https://repology.org/badge/vertical-allrepos/ruff-python-linter.svg?exclude_unsupported=1)](https://repology.org/project/ruff-python-linter/versions)

docs/usage.md

@@ -0,0 +1,42 @@
+# Using Ruff
+
+To run Ruff, try any of the following:
+
+```shell
+ruff check .                        # Lint all files in the current directory (and any subdirectories)
+ruff check path/to/code/            # Lint all files in `/path/to/code` (and any subdirectories)
+ruff check path/to/code/*.py        # Lint all `.py` files in `/path/to/code`
+ruff check path/to/code/to/file.py  # Lint `file.py`
+```
+
+You can run Ruff in `--watch` mode to automatically re-run on-change:
+
+```shell
+ruff check path/to/code/ --watch
+```
+
+Ruff can also be used as a [pre-commit](https://pre-commit.com) hook:
+
+```yaml
+- repo: https://github.com/charliermarsh/ruff-pre-commit
+  # Ruff version.
+  rev: 'v0.0.252'
+  hooks:
+    - id: ruff
+```
+
+Or, to enable autofix:
+
+```yaml
+- repo: https://github.com/charliermarsh/ruff-pre-commit
+  # Ruff version.
+  rev: 'v0.0.252'
+  hooks:
+    - id: ruff
+      args: [--fix, --exit-non-zero-on-fix]
+```
+
+Note that Ruff's pre-commit hook should run before Black, isort, and other formatting tools.
+
+Ruff can also be used as a [VS Code extension](https://github.com/charliermarsh/ruff-vscode) or
+alongside any other editor through the [Ruff LSP](https://github.com/charliermarsh/ruff-lsp).

scripts/generate_mkdocs.py

@@ -18,7 +18,8 @@ class Section(NamedTuple):
 
 SECTIONS: list[Section] = [
     Section("Overview", "index.md", generated=True),
-    Section("Installation and Usage", "installation-and-usage.md", generated=False),
+    Section("Installation", "installation.md", generated=False),
+    Section("Usage", "usage.md", generated=False),
     Section("Configuration", "configuration.md", generated=False),
     Section("Rules", "rules.md", generated=True),
     Section("Settings", "settings.md", generated=True),