]> git.madduck.net Git - etc/vim.git/blob - docs/index.md

madduck's git repository

Every one of the projects in this repository is available at the canonical URL git://git.madduck.net/madduck/pub/<projectpath> — see each project's metadata for the exact URL.

All patches and comments are welcome. Please squash your changes to logical commits before using git-format-patch and git-send-email to patches@git.madduck.net. If you'd read over the Git project's submission guidelines and adhered to them, I'd be especially grateful.

SSH access, as well as push access can be individually arranged.

If you use my repositories frequently, consider adding the following snippet to ~/.gitconfig and using the third clone URL listed for each project:

[url "git://git.madduck.net/madduck/"]
  insteadOf = madduck:

Add CITATION.cff file (#3723)
[etc/vim.git] / docs / index.md
1 <!--
2 black documentation master file, created by
3 sphinx-quickstart on Fri Mar 23 10:53:30 2018.
4 -->
5
6 # The uncompromising code formatter
7
8 > “Any color you like.”
9
10 By using _Black_, you agree to cede control over minutiae of hand-formatting. In return,
11 _Black_ gives you speed, determinism, and freedom from `pycodestyle` nagging about
12 formatting. You will save time and mental energy for more important matters.
13
14 _Black_ makes code review faster by producing the smallest diffs possible. Blackened
15 code looks the same regardless of the project you're reading. Formatting becomes
16 transparent after a while and you can focus on the content instead.
17
18 Try it out now using the [Black Playground](https://black.vercel.app).
19
20 ```{admonition} Note - Black is now stable!
21 *Black* is [successfully used](https://github.com/psf/black#used-by) by
22 many projects, small and big. *Black* has a comprehensive test suite, with efficient
23 parallel tests, our own auto formatting and parallel Continuous Integration runner.
24 Now that we have become stable, you should not expect large formatting to changes in
25 the future. Stylistic changes will mostly be responses to bug reports and support for new Python
26 syntax.
27
28 Also, as a safety measure which slows down processing, *Black* will check that the
29 reformatted code still produces a valid AST that is effectively equivalent to the
30 original (see the
31 [Pragmatism](./the_black_code_style/current_style.md#pragmatism)
32 section for details). If you're feeling confident, use `--fast`.
33 ```
34
35 ```{note}
36 {doc}`Black is licensed under the MIT license <license>`.
37 ```
38
39 ## Testimonials
40
41 **Mike Bayer**, author of [SQLAlchemy](https://www.sqlalchemy.org/):
42
43 > _I can't think of any single tool in my entire programming career that has given me a
44 > bigger productivity increase by its introduction. I can now do refactorings in about
45 > 1% of the keystrokes that it would have taken me previously when we had no way for
46 > code to format itself._
47
48 **Dusty Phillips**,
49 [writer](https://smile.amazon.com/s/ref=nb_sb_noss?url=search-alias%3Daps&field-keywords=dusty+phillips):
50
51 > _Black is opinionated so you don't have to be._
52
53 **Hynek Schlawack**, creator of [attrs](https://www.attrs.org/), core developer of
54 Twisted and CPython:
55
56 > _An auto-formatter that doesn't suck is all I want for Xmas!_
57
58 **Carl Meyer**, [Django](https://www.djangoproject.com/) core developer:
59
60 > _At least the name is good._
61
62 **Kenneth Reitz**, creator of [requests](http://python-requests.org/) and
63 [pipenv](https://docs.pipenv.org/):
64
65 > _This vastly improves the formatting of our code. Thanks a ton!_
66
67 ## Show your style
68
69 Use the badge in your project's README.md:
70
71 ```md
72 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
73 ```
74
75 Using the badge in README.rst:
76
77 ```rst
78 .. image:: https://img.shields.io/badge/code%20style-black-000000.svg
79    :target: https://github.com/psf/black
80 ```
81
82 Looks like this:
83
84 ```{image} https://img.shields.io/badge/code%20style-black-000000.svg
85 :target: https://github.com/psf/black
86 ```
87
88 ## Contents
89
90 ```{toctree}
91 ---
92 maxdepth: 3
93 includehidden:
94 ---
95
96 the_black_code_style/index
97 ```
98
99 ```{toctree}
100 ---
101 maxdepth: 3
102 includehidden:
103 caption: User Guide
104 ---
105
106 getting_started
107 usage_and_configuration/index
108 integrations/index
109 guides/index
110 faq
111 ```
112
113 ```{toctree}
114 ---
115 maxdepth: 2
116 includehidden:
117 caption: Development
118 ---
119
120 contributing/index
121 change_log
122 authors
123 ```
124
125 ```{toctree}
126 ---
127 hidden:
128 caption: Project Links
129 ---
130
131 GitHub <https://github.com/psf/black>
132 PyPI <https://pypi.org/project/black>
133 Chat <https://discord.gg/RtVdv86PrH>
134 ```
135
136 # Indices and tables
137
138 - {ref}`genindex`
139 - {ref}`search`