Unverified Commit 62bfbd6a authored by Richard Si's avatar Richard Si Committed by GitHub
Browse files

Reorganize docs v2 (GH-2174)

I know I know, this is the second reorganization of the docs. I'm not
saying the first one was bad or anything... but.. actually wait nah,
*it was bad*.

Anyway, welcome to probably my biggest commit. The main thing with this
reorganization was to introduce nesting to the documentation! Having
all of the docs be part of the main TOC was becoming too much. There
wasn't much room to expand either. Finally, the old setup required
a documentation generation step which was just annoying.

The goals of this reorganization was to:

1. Significantly restructure the docs to be discoverable and
   understandable

2. Add room for further docs (like guides or contributing docs)

3. Get rid of the doc generation step (it was slow and frustrating)

4. Unblock other improvements and also just make contributing to the
   docs easier

Another important change with this is that we are no longer using GitHub
as a documentation host. While GitHub does support Markdown based docs
actually pretty well, the lack of any features outside of GitHub Flavoured
Markdown is quite limiting. ReadTheDocs is just much better suited for
documentation. You can use reST, MyST, CommonMark, and all of their
great features like toctrees and admonitions.

Related to this change, we're adopting MyST as our flavour of Markdown.
MyST introduces neat syntax extensions to Markdown that pretty much
gives us the best of both worlds. The ease of use and simplicity of MD
and the flexibility and expressiveness of reST. Also recommonmark is
deprecated now. This switch was possible now we don't use GH as a docs
host. MyST docs have to be built to really be usable / pretty, so the MD
docs are going to look pretty bad on GH, but that's fine now!

Another thing that should be noted is that the README has been stripped
of most content since it was confusing. Users would read the README and
then think some feature or bug was fixed already and is available in a
release when in reality, they weren't. They were reading effectively
the latest docs without knowing.

See also: https://github.com/psf/black/issues/1759

FYI: CommonMark is a rationalized version of Markdown syntax

--

Commit history before merge:

* Switch to MyST-Parser + doc config cleanup

  recommonmark is being deprecated in favour of MyST-Parser. This change
  is welcomed, especially since MyST-Parser has syntax extensions for the
  Commonmark standard. Effectively we get to use a language that's powerful
  and expressive like ReST, but get the simplicity of Markdown.

  The rest of this effort will be using some MyST features.

  This reorganization efforts aims to remove as much duplication as possible.
  The regeneration step once needed is gone, significantly simplifing our
  Sphinx documentation configuration.

* Tell pipenv we replaced recommonmark for MyST-Parser

  Also update `docs/requirements.txt`

* Delete all auto generated content
* Switch prettier for mdformat (plus a few plugins)

  **FYI: THIS WAS EFFECTIVELY REVERTED, SEE THIRD TO LAST COMMIT**

  prettier doesn't support MyST's syntax extensions which are going to be
  used in this reorganization effort so we have to switch formatter.

  Unfortanately mdformat's style is different from prettier's so time to
  reformat the whole repo too.

  We're excluding .github/ISSUE_TEMPLATE because I have no idea whether
  its changes are safe, so let's play it safe.

* Fix the heading levels in CHANGES.md + a link

  MyST-Parser / sphinx's linkcheck complains otherwise.

* Move reference docs into a docs/contributing dir

  They're for contributors of Black anyway. Also added a note in the
  summary document warning about the lack of attention the reference has
  been dealing with.

* Rewrite and setup the new landing page + main TOC

  - add some more detail about Black's beta status
  - add licensing info
  - add external links in the main TOC for GitHub, PyPI, and IRC
  - prepare main TOC for new structure

* Break out AUTHORS into its own file

  Not only was the AUTHORS list quite long, this makes it easy to include
  it in the Sphinx docs with just a simple symlink.

* Add license to docs via a simple include

  Yes the document is orphaned but it is linked to in the landing page
  (docs/index.rst).

* Add "The Black Code Style" section

  This mostly was a restructuring commit, there has been a few updates but
  not many. The main goal was to split "current style" and "planned
  changes to the style that haven't happened yet" to avoid confusion.

* Add "Getting Started" page

  This is basically a quick start + even more. This commit is certainly
  one of most creatively involved in this effort.

* Add "Usage and Configuration" section

  This commit was as much restructuring as new content. Instead of being
  in one giant file, usage and configuration documentation can expand
  without bloating a single file.

* Add "Integrations" section

Just a restructuring commit ...

* Add "Guides" section

  This is a promising area of documentation that could easily grow in the
  future, let's prepare for that!

* Add "Contributing" section

  This is also another area that I expect to see significant growth in.
  Contributors to Black could definitely do with some more specific docs
  that clears up certain parts of our slightly confusing project (it's
  only confusing because we're getting big and old!).

* Rewrite CONTRIBUTING.md to just point to RTD
* Rewrite README.md to delegate most info to RTD
* Address feedback + a lot of corrections and edits

  I know I said I wanted to do these after landing this but given there's
  going to be no time between this being merged and a release getting
  pushed, I want these changes to make it in.

  - drop the number flag for mdformat - to reduce diffs, see also:
    https://mdformat.readthedocs.io/en/stable/users/style.html#ordered-lists
  - the GH issue templates should be safe by mdformat, so get rid of the
    exclude
  - clarify our configuration position - i.e. stop claiming we don't have
    many options, instead say we want as little formatting knobs as
    possible
  - lots and lots of punctuation, spelling, and grammar corrections (thanks
    Jelle!)
  - use RTD as the source for the CHANGELOG too
  - visual style cleanups
  - add docs about our .gitignore behaviour
  - expand GHA Action docs
  - clarify we want the PR number in the CHANGELOG entry
  - claify Black's behaviour for with statements post Python 3.9
  - italicize a bunch of "Black"s

  Thank you goes to Jelle, Taneli (hukkinj1 on GH), Felix
  (felix-hilden on GH), and Wouter (wbolster on GH) for the feedback!

* Merge remote-tracking branch 'upstream/master' into reorganize-docs-v2

  merge conflicts suck, although these ones weren't too bad.

* Add changelog entry + fix merge conflict resolution error

  I consider this important enough to be worthy of a changelog entry :)

* Merge branch 'master' into reorganize-docs-v2

  Co-authored-by: default avatarŁukasz Langa <lukasz@langa.pl>

* Actually let's continue using prettier

  Prettier works fine for all of the default MyST syntax so let's not
  rock the boat as much. Dropping the mdformat commit was merge-conflict
  filled so here's additional commit instead.

* Address Cooper's, Taneli's, and Jelle's feedback

  Lots of wording improvements by Cooper. Taneli suggested to disable the
  enabled by default MyST syntax not supported by Prettier and I agreed.
  And Jelle found one more spelling error!

* More minor fixes
parent 036bea4a
Loading
Loading
Loading
Loading
+7 −7
Changes for .github/ISSUE_TEMPLATE/bug_report.md: 7 added lines, 7 removed lines.
Original line number Diff line number Diff line
@@ -11,21 +11,21 @@ assignees: ""
**To Reproduce** Steps to reproduce the behavior:

1. Take this file '...'
2. Run _Black_ on it with these arguments '....'
3. See error
1. Run _Black_ on it with these arguments '....'
1. See error

**Expected behavior** A clear and concise description of what you expected to happen.

**Environment (please complete the following information):**

- Version: [e.g. master]
- OS and Python version: [e.g. Linux/Python 3.7.4rc1]
- Version: \[e.g. master\]
- OS and Python version: \[e.g. Linux/Python 3.7.4rc1\]

**Does this bug also happen on master?** To answer this, you have two options:

1. Use the online formatter at https://black.now.sh/?version=master, which will use the
   latest master branch.
2. Or run _Black_ on your machine:
1. Use the online formatter at <https://black.vercel.app/?version=master>, which will
   use the latest master branch.
1. Or run _Black_ on your machine:
   - create a new virtualenv (make sure it's the same Python version);
   - clone this repository;
   - run `pip install -e .[d,python2]`;
+1 −1
Changes for .github/ISSUE_TEMPLATE/feature_request.md: 1 added line, 1 removed line.
Original line number Diff line number Diff line
@@ -7,7 +7,7 @@ assignees: ""
---

**Is your feature request related to a problem? Please describe.** A clear and concise
description of what the problem is. Ex. I'm always frustrated when [...]
description of what the problem is. Ex. I'm always frustrated when \[...\]

**Describe the solution you'd like** A clear and concise description of what you want to
happen.

AUTHORS.md

0 → 100644
+184 −0
Changes for AUTHORS.md: 184 added lines, 0 removed lines.
Original line number Diff line number Diff line
# Authors

Glued together by [Łukasz Langa](mailto:lukasz@langa.pl).

Maintained with [Carol Willing](mailto:carolcode@willingconsulting.com),
[Carl Meyer](mailto:carl@oddbird.net),
[Jelle Zijlstra](mailto:jelle.zijlstra@gmail.com),
[Mika Naylor](mailto:mail@autophagy.io),
[Zsolt Dollenstein](mailto:zsol.zsol@gmail.com),
[Cooper Lees](mailto:me@cooperlees.com), and Richard Si.

Multiple contributions by:

- [Abdur-Rahmaan Janhangeer](mailto:arj.python@gmail.com)
- [Adam Johnson](mailto:me@adamj.eu)
- [Adam Williamson](mailto:adamw@happyassassin.net)
- [Alexander Huynh](mailto:github@grande.coffee)
- [Alex Vandiver](mailto:github@chmrr.net)
- [Allan Simon](mailto:allan.simon@supinfo.com)
- Anders-Petter Ljungquist
- [Andrew Thorp](mailto:andrew.thorp.dev@gmail.com)
- [Andrew Zhou](mailto:andrewfzhou@gmail.com)
- [Andrey](mailto:dyuuus@yandex.ru)
- [Andy Freeland](mailto:andy@andyfreeland.net)
- [Anthony Sottile](mailto:asottile@umich.edu)
- [Arjaan Buijk](mailto:arjaan.buijk@gmail.com)
- [Arnav Borbornah](mailto:arnavborborah11@gmail.com)
- [Artem Malyshev](mailto:proofit404@gmail.com)
- [Asger Hautop Drewsen](mailto:asgerdrewsen@gmail.com)
- [Augie Fackler](mailto:raf@durin42.com)
- [Aviskar KC](mailto:aviskarkc10@gmail.com)
- Batuhan Taşkaya
- [Benjamin Wohlwend](mailto:bw@piquadrat.ch)
- [Benjamin Woodruff](mailto:github@benjam.info)
- [Bharat Raghunathan](mailto:bharatraghunthan9767@gmail.com)
- [Brandt Bucher](mailto:brandtbucher@gmail.com)
- [Brett Cannon](mailto:brett@python.org)
- [Bryan Bugyi](mailto:bryan.bugyi@rutgers.edu)
- [Bryan Forbes](mailto:bryan@reigndropsfall.net)
- [Calum Lind](mailto:calumlind@gmail.com)
- [Charles](mailto:peacech@gmail.com)
- Charles Reid
- [Christian Clauss](mailto:cclauss@bluewin.ch)
- [Christian Heimes](mailto:christian@python.org)
- [Chuck Wooters](mailto:chuck.wooters@microsoft.com)
- [Chris Rose](mailto:offline@offby1.net)
- Codey Oxley
- [Cong](mailto:congusbongus@gmail.com)
- [Cooper Ry Lees](mailto:me@cooperlees.com)
- [Dan Davison](mailto:dandavison7@gmail.com)
- [Daniel Hahler](mailto:github@thequod.de)
- [Daniel M. Capella](mailto:polycitizen@gmail.com)
- Daniele Esposti
- [David Hotham](mailto:david.hotham@metaswitch.com)
- [David Lukes](mailto:dafydd.lukes@gmail.com)
- [David Szotten](mailto:davidszotten@gmail.com)
- [Denis Laxalde](mailto:denis@laxalde.org)
- [Douglas Thor](mailto:dthor@transphormusa.com)
- dylanjblack
- [Eli Treuherz](mailto:eli@treuherz.com)
- [Emil Hessman](mailto:emil@hessman.se)
- [Felix Kohlgrüber](mailto:felix.kohlgrueber@gmail.com)
- [Florent Thiery](mailto:fthiery@gmail.com)
- Francisco
- [Giacomo Tagliabue](mailto:giacomo.tag@gmail.com)
- [Greg Gandenberger](mailto:ggandenberger@shoprunner.com)
- [Gregory P. Smith](mailto:greg@krypto.org)
- Gustavo Camargo
- hauntsaninja
- [Hadi Alqattan](mailto:alqattanhadizaki@gmail.com)
- [Heaford](mailto:dan@heaford.com)
- [Hugo Barrera](mailto::hugo@barrera.io)
- Hugo van Kemenade
- [Hynek Schlawack](mailto:hs@ox.cx)
- [Ivan Katanić](mailto:ivan.katanic@gmail.com)
- [Jakub Kadlubiec](mailto:jakub.kadlubiec@skyscanner.net)
- [Jakub Warczarek](mailto:jakub.warczarek@gmail.com)
- [Jan Hnátek](mailto:jan.hnatek@gmail.com)
- [Jason Fried](mailto:me@jasonfried.info)
- [Jason Friedland](mailto:jason@friedland.id.au)
- [jgirardet](mailto:ijkl@netc.fr)
- Jim Brännlund
- [Jimmy Jia](mailto:tesrin@gmail.com)
- [Joe Antonakakis](mailto:jma353@cornell.edu)
- [Jon Dufresne](mailto:jon.dufresne@gmail.com)
- [Jonas Obrist](mailto:ojiidotch@gmail.com)
- [Jonty Wareing](mailto:jonty@jonty.co.uk)
- [Jose Nazario](mailto:jose.monkey.org@gmail.com)
- [Joseph Larson](mailto:larson.joseph@gmail.com)
- [Josh Bode](mailto:joshbode@fastmail.com)
- [Josh Holland](mailto:anowlcalledjosh@gmail.com)
- [Joshua Cannon](mailto:joshdcannon@gmail.com)
- [José Padilla](mailto:jpadilla@webapplicate.com)
- [Juan Luis Cano Rodríguez](mailto:hello@juanlu.space)
- [kaiix](mailto:kvn.hou@gmail.com)
- [Katie McLaughlin](mailto:katie@glasnt.com)
- Katrin Leinweber
- [Keith Smiley](mailto:keithbsmiley@gmail.com)
- [Kenyon Ralph](mailto:kenyon@kenyonralph.com)
- [Kevin Kirsche](mailto:Kev.Kirsche+GitHub@gmail.com)
- [Kyle Hausmann](mailto:kyle.hausmann@gmail.com)
- [Kyle Sunden](mailto:sunden@wisc.edu)
- Lawrence Chan
- [Linus Groh](mailto:mail@linusgroh.de)
- [Loren Carvalho](mailto:comradeloren@gmail.com)
- [Luka Sterbic](mailto:luka.sterbic@gmail.com)
- [LukasDrude](mailto:mail@lukas-drude.de)
- Mahmoud Hossam
- Mariatta
- [Matt VanEseltine](mailto:vaneseltine@gmail.com)
- [Matthew Clapp](mailto:itsayellow+dev@gmail.com)
- [Matthew Walster](mailto:matthew@walster.org)
- Max Smolens
- [Michael Aquilina](mailto:michaelaquilina@gmail.com)
- [Michael Flaxman](mailto:michael.flaxman@gmail.com)
- [Michael J. Sullivan](mailto:sully@msully.net)
- [Michael McClimon](mailto:michael@mcclimon.org)
- [Miguel Gaiowski](mailto:miggaiowski@gmail.com)
- [Mike](mailto:roshi@fedoraproject.org)
- [mikehoyio](mailto:mikehoy@gmail.com)
- [Min ho Kim](mailto:minho42@gmail.com)
- [Miroslav Shubernetskiy](mailto:miroslav@miki725.com)
- MomIsBestFriend
- [Nathan Goldbaum](mailto:ngoldbau@illinois.edu)
- [Nathan Hunt](mailto:neighthan.hunt@gmail.com)
- [Neraste](mailto:neraste.herr10@gmail.com)
- [Nikolaus Waxweiler](mailto:madigens@gmail.com)
- [Ofek Lev](mailto:ofekmeister@gmail.com)
- [Osaetin Daniel](mailto:osaetindaniel@gmail.com)
- [otstrel](mailto:otstrel@gmail.com)
- [Pablo Galindo](mailto:Pablogsal@gmail.com)
- [Paul Ganssle](mailto:p.ganssle@gmail.com)
- [Paul Meinhardt](mailto:mnhrdt@gmail.com)
- [Peter Bengtsson](mailto:mail@peterbe.com)
- [Peter Grayson](mailto:pete@jpgrayson.net)
- [Peter Stensmyr](mailto:peter.stensmyr@gmail.com)
- pmacosta
- [Quentin Pradet](mailto:quentin@pradet.me)
- [Ralf Schmitt](mailto:ralf@systemexit.de)
- [Ramón Valles](mailto:mroutis@protonmail.com)
- [Richard Fearn](mailto:richardfearn@gmail.com)
- [Rishikesh Jha](mailto:rishijha424@gmail.com)
- [Rupert Bedford](mailto:rupert@rupertb.com)
- Russell Davis
- [Rémi Verschelde](mailto:rverschelde@gmail.com)
- [Sami Salonen](mailto:sakki@iki.fi)
- [Samuel Cormier-Iijima](mailto:samuel@cormier-iijima.com)
- [Sanket Dasgupta](mailto:sanketdasgupta@gmail.com)
- Sergi
- [Scott Stevenson](mailto:scott@stevenson.io)
- Shantanu
- [shaoran](mailto:shaoran@sakuranohana.org)
- [Shinya Fujino](mailto:shf0811@gmail.com)
- springstan
- [Stavros Korokithakis](mailto:hi@stavros.io)
- [Stephen Rosen](mailto:sirosen@globus.org)
- [Steven M. Vascellaro](mailto:S.Vascellaro@gmail.com)
- [Sunil Kapil](mailto:snlkapil@gmail.com)
- [Sébastien Eustace](mailto:sebastien.eustace@gmail.com)
- [Tal Amuyal](mailto:TalAmuyal@gmail.com)
- [Terrance](mailto:git@terrance.allofti.me)
- [Thom Lu](mailto:thomas.c.lu@gmail.com)
- [Thomas Grainger](mailto:tagrain@gmail.com)
- [Tim Gates](mailto:tim.gates@iress.com)
- [Tim Swast](mailto:swast@google.com)
- [Timo](mailto:timo_tk@hotmail.com)
- Toby Fleming
- [Tom Christie](mailto:tom@tomchristie.com)
- [Tony Narlock](mailto:tony@git-pull.com)
- [Tsuyoshi Hombashi](mailto:tsuyoshi.hombashi@gmail.com)
- [Tushar Chandra](mailto:tusharchandra2018@u.northwestern.edu)
- [Tzu-ping Chung](mailto:uranusjr@gmail.com)
- [Utsav Shah](mailto:ukshah2@illinois.edu)
- utsav-dbx
- vezeli
- [Ville Skyttä](mailto:ville.skytta@iki.fi)
- [Vishwas B Sharma](mailto:sharma.vishwas88@gmail.com)
- [Vlad Emelianov](mailto:volshebnyi@gmail.com)
- [williamfzc](mailto:178894043@qq.com)
- [wouter bolsterlee](mailto:wouter@bolsterl.ee)
- Yazdan
- [Yngve Høiseth](mailto:yngve@hoiseth.net)
- [Yurii Karabas](mailto:1998uriyyo@gmail.com)
- [Zac Hatfield-Dodds](mailto:zac@zhd.dev)
+51 −43
Changes for CHANGES.md: 51 added lines, 43 removed lines.
Original line number Diff line number Diff line
## Change Log
# Change Log

### Unreleased
## Unreleased

#### _Black_
### _Black_

- Refactor `src/black/__init__.py` into many files (#2206)

### 21.5b0
### Documentation

#### _Black_
- Sigificantly reorganized the documentation to make much more sense. Check them out by
  heading over to [the stable docs on RTD](https://black.readthedocs.io/en/stable/).
  (#2174)

## 21.5b0

### _Black_

- Set `--pyi` mode if `--stdin-filename` ends in `.pyi` (#2169)
- Stop detecting target version as Python 3.9+ with pre-PEP-614 decorators that are
  being called but with no arguments (#2182)

#### _Black-Primer_
### _Black-Primer_

- Add `--no-diff` to black-primer to suppress formatting changes (#2187)

### 21.4b2
## 21.4b2

#### _Black_
### _Black_

- Fix crash if the user configuration directory is inaccessible. (#2158)

@@ -31,15 +37,15 @@
- Allow `.gitignore` rules to be overridden by specifying `exclude` in `pyproject.toml`
  or on the command line. (#2170)

#### _Packaging_
### _Packaging_

- Install `primer.json` (used by `black-primer` by default) with black. (#2154)

### 21.4b1
## 21.4b1

#### _Black_
### _Black_

- Fix crash on docstrings ending with "\ ". (#2142)
- Fix crash on docstrings ending with "\\ ". (#2142)

- Fix crash when atypical whitespace is cleaned out of dostrings (#2120)

@@ -50,13 +56,13 @@
- Don't remove necessary parentheses from assignment expression containing assert /
  return statements. (#2143)

#### _Packaging_
### _Packaging_

- Bump pathspec to >= 0.8.1 to solve invalid .gitignore exclusion handling

### 21.4b0
## 21.4b0

#### _Black_
### _Black_

- Fixed a rare but annoying formatting instability created by the combination of
  optional trailing commas inserted by `Black` and optional parentheses looking at
@@ -112,21 +118,21 @@
- Fixed "Black produced code that is not equivalent to the source" when formatting
  Python 2 docstrings (#2037)

#### _Packaging_
### _Packaging_

- Self-contained native _Black_ binaries are now provided for releases via GitHub
  Releases (#1743)

### 20.8b1
## 20.8b1

#### _Packaging_
### _Packaging_

- explicitly depend on Click 7.1.2 or newer as `Black` no longer works with versions
  older than 7.0

### 20.8b0
## 20.8b0

#### _Black_
### _Black_

- re-implemented support for explicit trailing commas: now it works consistently within
  any bracket pair, including nested structures (#1288 and duplicates)
@@ -170,11 +176,11 @@
  this is an undocumented and unsupported feature, you lose Internet points for
  depending on it (#1609)

#### Vim plugin
### Vim plugin

- prefer virtualenv packages over global packages (#1383)

### 19.10b0
## 19.10b0

- added support for PEP 572 assignment expressions (#711)

@@ -233,7 +239,7 @@
- `blackd` can now output the diff of formats on source code when the `X-Diff` header is
  provided (#969)

### 19.3b0
## 19.3b0

- new option `--target-version` to control which Python versions _Black_-formatted code
  should target (#618)
@@ -258,7 +264,7 @@

- `blackd` now supports CORS (#622)

### 18.9b0
## 18.9b0

- numeric literals are now formatted by _Black_ (#452, #461, #464, #469):

@@ -273,7 +279,9 @@

  - hexadecimal digits are always uppercased (e.g. `0xBADC0DE`)

- added `blackd`, see [its documentation](#blackd) for more info (#349)
- added `blackd`, see
  [its documentation](https://github.com/psf/black/blob/18.9b0/README.md#blackd) for
  more info (#349)

- adjacent string literals are now correctly split into multiple lines (#463)

@@ -300,11 +308,11 @@
- note: the Vim plugin stopped registering `,=` as a default chord as it turned out to
  be a bad idea (#415)

### 18.6b4
## 18.6b4

- hotfix: don't freeze when multiple comments directly precede `# fmt: off` (#371)

### 18.6b3
## 18.6b3

- typing stub files (`.pyi`) now have blank lines added after constants (#340)

@@ -332,7 +340,7 @@

- fixed a crash due to symbolic links pointing outside of the project directory (#338)

### 18.6b2
## 18.6b2

- added `--config` (#65)

@@ -346,13 +354,13 @@

- fixed unnecessary slowdown in comment placement calculation on lines without comments

### 18.6b1
## 18.6b1

- hotfix: don't output human-facing information on stdout (#299)

- hotfix: don't output cake emoji on non-zero return code (#300)

### 18.6b0
## 18.6b0

- added `--include` and `--exclude` (#270)

@@ -370,7 +378,7 @@

- _Black_ now preserves line endings when formatting a file in place (#258)

### 18.5b1
## 18.5b1

- added `--pyi` (#249)

@@ -399,7 +407,7 @@
- fixed extra empty line between a function signature and an inner function or inner
  class (#196)

### 18.5b0
## 18.5b0

- call chains are now formatted according to the
  [fluent interfaces](https://en.wikipedia.org/wiki/Fluent_interface) style (#67)
@@ -454,11 +462,11 @@

- fixed crash when dead symlinks where encountered

### 18.4a4
## 18.4a4

- don't populate the cache on `--check` (#175)

### 18.4a3
## 18.4a3

- added a "cache"; files already reformatted that haven't changed on disk won't be
  reformatted again (#109)
@@ -486,7 +494,7 @@

- fixed missing splits of ternary expressions (#141)

### 18.4a2
## 18.4a2

- fixed parsing of unaligned standalone comments (#99, #112)

@@ -497,7 +505,7 @@
- fixed unstable formatting when encountering unnecessarily escaped quotes in a string
  (#120)

### 18.4a1
## 18.4a1

- added `--quiet` (#78)

@@ -509,7 +517,7 @@

- fixed removing backslash escapes from raw strings (#100, #105)

### 18.4a0
## 18.4a0

- added `--diff` (#87)

@@ -534,7 +542,7 @@
- only allow up to two empty lines on module level and only single empty lines within
  functions (#74)

### 18.3a4
## 18.3a4

- `# fmt: off` and `# fmt: on` are implemented (#5)

@@ -556,7 +564,7 @@
  [Sphinx auto-attribute comments](http://www.sphinx-doc.org/en/stable/ext/autodoc.html#directive-autoattribute)
  (#68)

### 18.3a3
## 18.3a3

- don't remove single empty lines outside of bracketed expressions (#19)

@@ -566,7 +574,7 @@

- even better handling of numpy-style array indexing (#33, again)

### 18.3a2
## 18.3a2

- changed positioning of binary operators to occur at beginning of lines instead of at
  the end, following
@@ -590,7 +598,7 @@

- fixed spurious space after star-based unary expressions (#31)

### 18.3a1
## 18.3a1

- added `--check`

@@ -609,10 +617,10 @@
- fixed spurious space after unary operators when the operand was a complex expression
  (#15)

### 18.3a0
## 18.3a0

- first published version, Happy 🍰 Day 2018!

- alpha quality

- date-versioned (see: https://calver.org/)
- date-versioned (see: <https://calver.org/>)
+4 −110
Changes for CONTRIBUTING.md: 4 added lines, 110 removed lines.
Original line number Diff line number Diff line
@@ -3,114 +3,8 @@
Welcome! Happy to see you willing to make the project better. Have you read the entire
[user documentation](https://black.readthedocs.io/en/latest/) yet?

## Bird's eye view
Our [contributing documentation](https://black.readthedocs.org/en/latest/contributing/)
contains details on all you need to know about contributing to _Black_, the basics to
the internals of _Black_.

In terms of inspiration, _Black_ is about as configurable as _gofmt_. This is
deliberate.

Bug reports and fixes are always welcome! Please follow the
[issue template on GitHub](https://github.com/psf/black/issues/new) for best results.

Before you suggest a new feature or configuration knob, ask yourself why you want it. If
it enables better integration with some workflow, fixes an inconsistency, speeds things
up, and so on - go for it! On the other hand, if your answer is "because I don't like a
particular formatting" then you're not ready to embrace _Black_ yet. Such changes are
unlikely to get accepted. You can still try but prepare to be disappointed.

## Technicalities

Development on the latest version of Python is preferred. As of this writing it's 3.9.
You can use any operating system. I am using macOS myself and CentOS at work.

Install all development dependencies using:

```console
$ pipenv install --dev
$ pipenv shell
$ pre-commit install
```

If you haven't used `pipenv` before but are comfortable with virtualenvs, just run
`pip install pipenv` in the virtualenv you're already using and invoke the command above
from the cloned _Black_ repo. It will do the correct thing.

Non pipenv install works too:

```console
$ pip install -r test_requirements
$ pip install -e .[d]
```

Before submitting pull requests, run lints and tests with the following commands from
the root of the black repo:

```console
# Linting
$ pre-commit run -a

# Unit tests
$ tox -e py

# Optional Fuzz testing
$ tox -e fuzz

# Optional CI run to test your changes on many popular python projects
$ black-primer [-k -w /tmp/black_test_repos]
```

### News / Changelog Requirement

`Black` has CI that will check for an entry corresponding to your PR in `CHANGES.md`. If
you feel this PR not require a changelog entry please state that in a comment and a
maintainer can add a `skip news` label to make the CI pass. Otherwise, please ensure you
have a line in the following format:

```md
- `Black` is now more awesome (#X)
```

To workout X, please use
[Next PR Number](https://ichard26.github.io/next-pr-number/?owner=psf&name=black). This
is not perfect but saves a lot of release overhead as now the releaser does not need to
go back and workout what to add to the `CHANGES.md` for each release.

### Style Changes

If a change would affect the advertised code style, please modify the documentation (The
_Black_ code style) to reflect that change. Patches that fix unintended bugs in
formatting don't need to be mentioned separately though.

### Docs Testing

If you make changes to docs, you can test they still build locally too.

```console
$ pip install -r docs/requirements.txt
$ pip install [-e] .[d]
$ sphinx-build -a -b html -W docs/ docs/_build/
```

## black-primer

`black-primer` is used by CI to pull down well-known _Black_ formatted projects and see
if we get source code changes. It will error on formatting changes or errors. Please run
before pushing your PR to see if you get the actions you would expect from _Black_ with
your PR. You may need to change
[primer.json](https://github.com/psf/black/blob/master/src/black_primer/primer.json)
configuration for it to pass.

For more `black-primer` information visit the
[documentation](https://github.com/psf/black/blob/master/docs/black_primer.md).

## Hygiene

If you're fixing a bug, add a test. Run it first to confirm it fails, then fix the bug,
run it again to confirm it's really fixed.

If adding a new feature, add a test. In fact, always add a test. But wait, before adding
any large feature, first open an issue for us to discuss the idea first.

## Finally

Thanks again for your interest in improving the project! You're taking action when most
people decide to sit and watch.
We look forward to your contributions!
Loading