Add Black compatible configurations in documentation (#1366 & #1205) #1371

ichard26 · 2020-04-29T22:27:17Z

Resolves #1366 and resolves #1205.

Please be warned, this is my first pull request and my first attempt at writing decent documentation.
So feel free to mention if I've done anything wrong or if my documentation is lacking in quality.

~~Note that this PR isn't ready for review since some work needs to be finished:~~

I need to add references in README. I haven't done it yet since I'm too scared of touching the README ... It's the front page of this project.
I should add explanations for the configurations since copying and pasting code you don't understand is always a horrible idea.

Also, while I did test all of the configurations to verify that they work with their respective tools, I may have missed a few options. I went for the least amount of configuration possible.

Once again, any comments/suggestions on my PR, my commit messages, or my actual documentation are welcome! Also so are comments/suggestions on how I should link from the README.

P.S: Thanks for this tool, it's really useful!

When users of Black are starting a new project or are adding Black to their existing projects, they will usually have to config their existing tools like flake8 to be compatible with Black. Usually, these configs are the same across different projects. Yet, there isn't any consolidated infomation on what configs are compatible. Leaving users of Black to dig out any infomation they can find in README.md.

ichard26 · 2020-04-29T23:15:27Z

b914650 Whoops, looks like I missed changing my testing value. max-line-length = 79 is now fixed to max-line-length = 88.

Copying and pasting code without understanding it is a bad idea. This goes the same for users copying and pasting configurations.

docs/compatible_configs.md

I referenced the wrong source. I used a pesonal configuration, not a pure Black- compatible configuration.

The explanation for the isort configuration was pretty bad. After having fixed the configuration (see commit 01c55d1), improving the its explanation was necessary to make it more user-friendly and understandable. Also added fenced code blocks of the raw configuration options so the explanations make sense.

cooperlees

Thanks for this. I just slightly dislike the direct call out to isort. I might merge and change this to be a little more gentle and we get another maintainer's approval.

cooperlees · 2020-05-08T13:44:19Z

README.md

+
+While _Black_ enforces formatting that conforms to PEP 8, other tools may raise warnings
+about _Black_'s changes or will overwrite _Black_'s changes... I am looking at you
+[isort](https://pypi.org/p/isort). Since _Black_ is barely configurable, these tools


I don't think we should call out isort directly. It was never designed to work with black. Can we remove this please or reword to be a little more subtle.
"A good example here is isort"

Yeah, I agree. In hindsight, isort and Black were never designed to be compatible with each other and it's unfair to call out isort for that. I'll try to reword it to more gentle or just remove it if I fail at doing that.

JelleZijlstra · 2020-05-08T13:54:08Z

docs/compatible_configs.md

@@ -0,0 +1,261 @@
+# _Black_ compatible configurations
+
+Most of the changes that _Black_ make are harmless, but a few do conflict against other


All of Black's changes are harmless (or at least, they should be)

Well noted, I think I've been stalking the issue section a bit too much.

JelleZijlstra · 2020-05-08T13:55:00Z

docs/compatible_configs.md

+[flake8](https://pypi.org/p/flake8/) is a code linter. It warns you of syntax errors,
+possible bugs, stylistic errors, etc. For the most part, flake8 follows
+[PEP 8](https://www.python.org/dev/peps/pep-0008/) when warning about stylistic errors.
+Except, there are a few deviations that cause incompatiblities with _Black_.


Suggested change

Except, there are a few deviations that cause incompatiblities with _Black_.

There are a few deviations that cause incompatibilities with _Black_.

JelleZijlstra · 2020-05-08T13:55:45Z

docs/compatible_configs.md

+)
+```
+
+Although, while this style is PEP 8 compliant, Pylint will raise


Suggested change

Although, while this style is PEP 8 compliant, Pylint will raise

Although this style is PEP 8 compliant, Pylint will raise

hugovk

flake8 -> Flake8

re: https://flake8.pycqa.org/en/latest/

hugovk · 2020-05-08T14:13:08Z

docs/compatible_configs.md

+
+</details>
+
+## flake8


Suggested change

## flake8

## Flake8

hugovk · 2020-05-08T14:13:16Z

docs/compatible_configs.md

+
+## flake8
+
+[flake8](https://pypi.org/p/flake8/) is a code linter. It warns you of syntax errors,


Suggested change

[flake8](https://pypi.org/p/flake8/) is a code linter. It warns you of syntax errors,

[Flake8](https://pypi.org/p/flake8/) is a code linter. It warns you of syntax errors,

hugovk · 2020-05-08T14:13:26Z

docs/compatible_configs.md

+## flake8
+
+[flake8](https://pypi.org/p/flake8/) is a code linter. It warns you of syntax errors,
+possible bugs, stylistic errors, etc. For the most part, flake8 follows


Suggested change

possible bugs, stylistic errors, etc. For the most part, flake8 follows

possible bugs, stylistic errors, etc. For the most part, Flake8 follows

hugovk · 2020-05-08T14:13:46Z

docs/compatible_configs.md

+`W503 line break before binary operator` warnings.
+
+In some cases, as determined by PEP 8, _Black_ will enforce an equal amount of
+whitespace around slice operators. Due to this, flake8 will raise


Suggested change

whitespace around slice operators. Due to this, flake8 will raise

whitespace around slice operators. Due to this, Flake8 will raise

hugovk · 2020-05-08T14:13:54Z

docs/compatible_configs.md

+whitespace around slice operators. Due to this, flake8 will raise
+`E203 whitespace before ':'` warnings.
+
+Since both of these warnings are not PEP 8 compliant, flake8 should be configured to


Suggested change

Since both of these warnings are not PEP 8 compliant, flake8 should be configured to

Since both of these warnings are not PEP 8 compliant, Flake8 should be configured to

hugovk · 2020-05-08T14:14:15Z

docs/compatible_configs.md

+Since both of these warnings are not PEP 8 compliant, flake8 should be configured to
+ignore these warnings via `extend-ignore = E203, W503`.
+
+Also, as like with isort, flake8 should be configured to allow lines up to the length


Suggested change

Also, as like with isort, flake8 should be configured to allow lines up to the length

Also, as like with isort, Flake8 should be configured to allow lines up to the length

hugovk · 2020-05-08T14:14:42Z

docs/compatible_configs.md

+
+## Pylint
+
+[Pylint](https://pypi.org/p/pylint/) is also a code linter like flake8. It has the same


Suggested change

[Pylint](https://pypi.org/p/pylint/) is also a code linter like flake8. It has the same

[Pylint](https://pypi.org/p/pylint/) is also a code linter like Flake8. It has the same

cooperlees · 2020-05-08T14:29:21Z

@ichard26 - I made the changes and merged! Thanks. We're having a black maintainers merge-a-thon today to try get black to become a python package - as per #1376

ichard26 · 2020-05-08T14:31:19Z

Oh well, I was going to add a commit with your very well noted suggestions but looks like you beat me to it. Thank you for putting in time for the PR regardless! It was a good first experience for contributing to open source.

We're having a black maintainers merge-a-thon

Oh yeah I can tell, my poor little email is getting spammed... good sign though!

ichard26 changed the title ~~Add Black compatible configs in docs (#1366 & #1205)~~ Add Black compatible configurations in documentation (#1366 & #1205) Apr 29, 2020

Fix a bad max-line-length value

b914650

ichard26 added 5 commits April 30, 2020 13:42

Merge branch 'master' into compatible_configs_doc

073f5e5

Clean up pylint's configs

5fd65a7

Add explanations for each configurations

a69d620

Copying and pasting code without understanding it is a bad idea. This goes the same for users copying and pasting configurations.

Capitalize Pylint

29fff64

Link from the README

01c55d1

ichard26 commented May 2, 2020

View reviewed changes

docs/compatible_configs.md Outdated Show resolved Hide resolved

ichard26 marked this pull request as ready for review May 2, 2020 19:08

ichard26 added 3 commits May 6, 2020 14:27

Fix the isort configuration

c63d9b6

I referenced the wrong source. I used a pesonal configuration, not a pure Black- compatible configuration.

Improve README wording slightly

7b8c163

cooperlees self-assigned this May 8, 2020

cooperlees approved these changes May 8, 2020

View reviewed changes

JelleZijlstra reviewed May 8, 2020

View reviewed changes

hugovk reviewed May 8, 2020

View reviewed changes

zsol added the T: documentation Improvements to the docs (e.g. new topic, correction, etc) label May 8, 2020

Add @hugovk, @JelleZijlstra + my suggestions

9409d2b

cooperlees merged commit 8c3c190 into psf:master May 8, 2020

ichard26 deleted the compatible_configs_doc branch May 8, 2020 14:58

zsol mentioned this pull request May 15, 2020

Colon inside a range gets a colon added to it #1413

Closed

ichard26 mentioned this pull request Jun 4, 2020

Provide lists of lint / pycodestyle rules that Black makes obsolete #429

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add Black compatible configurations in documentation (#1366 & #1205) #1371

Add Black compatible configurations in documentation (#1366 & #1205) #1371

ichard26 commented Apr 29, 2020 •

edited

Loading

ichard26 commented Apr 29, 2020

cooperlees left a comment

cooperlees May 8, 2020

ichard26 May 8, 2020 •

edited

Loading

JelleZijlstra May 8, 2020

ichard26 May 8, 2020

JelleZijlstra May 8, 2020

JelleZijlstra May 8, 2020

hugovk left a comment

hugovk May 8, 2020

hugovk May 8, 2020

hugovk May 8, 2020

hugovk May 8, 2020

hugovk May 8, 2020

hugovk May 8, 2020

hugovk May 8, 2020

cooperlees commented May 8, 2020

ichard26 commented May 8, 2020 •

edited

Loading

		@@ -0,0 +1,261 @@
		# _Black_ compatible configurations

		Most of the changes that _Black_ make are harmless, but a few do conflict against other

	Except, there are a few deviations that cause incompatiblities with _Black_.
	There are a few deviations that cause incompatibilities with _Black_.

	Although, while this style is PEP 8 compliant, Pylint will raise
	Although this style is PEP 8 compliant, Pylint will raise


		## flake8

		[flake8](https://pypi.org/p/flake8/) is a code linter. It warns you of syntax errors,

	possible bugs, stylistic errors, etc. For the most part, flake8 follows
	possible bugs, stylistic errors, etc. For the most part, Flake8 follows

	whitespace around slice operators. Due to this, flake8 will raise
	whitespace around slice operators. Due to this, Flake8 will raise

	Since both of these warnings are not PEP 8 compliant, flake8 should be configured to
	Since both of these warnings are not PEP 8 compliant, Flake8 should be configured to

	Also, as like with isort, flake8 should be configured to allow lines up to the length
	Also, as like with isort, Flake8 should be configured to allow lines up to the length


		## Pylint

		[Pylint](https://pypi.org/p/pylint/) is also a code linter like flake8. It has the same


		</details>

		## flake8

Add Black compatible configurations in documentation (#1366 & #1205) #1371

Add Black compatible configurations in documentation (#1366 & #1205) #1371

Conversation

ichard26 commented Apr 29, 2020 • edited Loading

ichard26 commented Apr 29, 2020

cooperlees left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ichard26 May 8, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hugovk left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cooperlees commented May 8, 2020

ichard26 commented May 8, 2020 • edited Loading

ichard26 commented Apr 29, 2020 •

edited

Loading

ichard26 May 8, 2020 •

edited

Loading

ichard26 commented May 8, 2020 •

edited

Loading