Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: Move fmt: off docs #4090

Merged
merged 2 commits into from
Dec 10, 2023
Merged

docs: Move fmt: off docs #4090

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
40a9860
docs: Move `fmt: off` docs
RedGuy12 Dec 8, 2023
89ef4d3
Merge branch 'main' into gh-2365
RedGuy12 Dec 8, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
15 changes: 3 additions & 12 deletions docs/the_black_code_style/current_style.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,18 +8,9 @@ deliberately limited and rarely added. Previous formatting is taken into account
little as possible, with rare exceptions like the magic trailing comma. The coding style
used by _Black_ can be viewed as a strict subset of PEP 8.

_Black_ reformats entire files in place. It doesn't reformat lines that contain
`# fmt: skip` or blocks that start with `# fmt: off` and end with `# fmt: on`.
`# fmt: skip` can be mixed with other pragmas/comments either with multiple comments
(e.g. `# fmt: skip # pylint # noqa`) or as a semicolon separated list (e.g.
`# fmt: skip; pylint; noqa`). `# fmt: on/off` must be on the same level of indentation
and in the same block, meaning no unindents beyond the initial indentation level between
them. It also recognizes [YAPF](https://github.com/google/yapf)'s block comments to the
same effect, as a courtesy for straddling code.

The rest of this document describes the current formatting style. If you're interested
in trying out where the style is heading, see [future style](./future_style.md) and try
running `black --preview`.
This document describes the current formatting style. If you're interested in trying out
where the style is heading, see [future style](./future_style.md) and try running
`black --preview`.

### How _Black_ wraps lines

Expand Down
16 changes: 14 additions & 2 deletions docs/usage_and_configuration/the_basics.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,8 @@ _Black_ is a well-behaved Unix-style command-line tool:

## Usage

To get started right away with sensible defaults:
_Black_ will reformat entire files in place. To get started right away with sensible
defaults:

```sh
black {source_file_or_directory}
Expand All @@ -24,6 +25,17 @@ You can run _Black_ as a package if running it as a script doesn't work:
python -m black {source_file_or_directory}
```

### Ignoring sections

Black will not reformat lines that contain `# fmt: skip` or blocks that start with
`# fmt: off` and end with `# fmt: on`. `# fmt: skip` can be mixed with other
pragmas/comments either with multiple comments (e.g. `# fmt: skip # pylint # noqa`) or
as a semicolon separated list (e.g. `# fmt: skip; pylint; noqa`). `# fmt: on/off` must
be on the same level of indentation and in the same block, meaning no unindents beyond
the initial indentation level between them. Black also recognizes
[YAPF](https://github.com/google/yapf)'s block comments to the same effect, as a
courtesy for straddling code.

### Command line options

The CLI options of _Black_ can be displayed by running `black --help`. All options are
Expand Down Expand Up @@ -191,7 +203,7 @@ All done! ✨ 🍰 ✨

Show (or do not show) colored diff. Only applies when `--diff` is given.

### `--line-ranges`
#### `--line-ranges`

When specified, _Black_ will try its best to only format these lines.

Expand Down