Create PEP 8-style document with the intended formatting style explicitly described

[ambv]

This will help users identify whether what they see is a bug or a feature.

A document like this also helps with giving reasons for specific behavior.

[willingc]

@ambv Using Black and loving it, are you planning on using Sphinx or something else? Happy to help get things started if Sphinx.

[ambv]

Yes, Sphinx and RTFD would be my first choice :-)

[willingc]

@ambv Can you link to an example of the pep8 style doc that you were thinking? The pep itself or something else. Thanks.

[ambv]

PEP 8 itself is good but wordy. Google Style Guide is also good.

[willingc]

@ambv @carljm Giving some thought to this. In some cases, Original and After Black will be helpful to illustrate what will happen. Initially, I'm starting with something similar to:

• Guide contents: https://test-black.readthedocs.io/en/style-guide/style_guide/style_guide.html
• Rule example: https://test-black.readthedocs.io/en/style-guide/style_guide/guards.html

My current thinking is that Original/After Black examples will cut down on wordiness in PEP8.

Side by side code displays could be cool too.

[SanketDG]

@ambv If I understand correctly, this has already been superseded by "The Black Code Style", yes?

[mcsitter]

The Black code style appears to b quite complete. Are there things missing?

[felix-hilden]

Another ping, since this issue is on the "Amazing documentation" project. I do second the earlier commenters. Is there a need for further documentation on this front?

[ichard26]

@felix-hilden I think the state of the style documentation is way better as of lately, but there's still a few areas which are missing:

1. the extra string handling Black has (currently locked away under a --experimental-string-processing flag); and
2. the docstring formatting Black does (I wouldn't recommend trying to add docs for them right now though since they will probably change since the current handling is IIRC a mistake from some other patch)

[felix-hilden]

I see, thanks! Would you accept contributions for the first one?

[ichard26]

@felix-hilden indeed! I'll be ever so annoyed at you for worsening the eventual merge conflict I'll have to deal with when I submit my documentation reorganization PR (hopefully soon!), but that's more on me for not finishing it quick enough ;-)

[felix-hilden]

I'll make sure then to beat you to the punch by the smallest possible margin 😄

From the discussions in #1740 I might also try to include some info on the docstring processing.

[felix-hilden]

Now that the missing information was added to the style documentation, and instructions on modifying said documentation was also added to CONTRIBUTING.md, future style-modifying PRs will carry their own weight in terms of documentation.

Is this issue ready to be closed?