X-Git-Url: https://git.madduck.net/etc/vim.git/blobdiff_plain/0a340e1f227c3705ed1b0dbbbf634c98e2e82ada..71e71e5f52e5f6bdeae63cc8c11b1bee44d11c30:/docs/index.rst?ds=inline diff --git a/docs/index.rst b/docs/index.rst index df59f71..8a8da0d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -4,7 +4,9 @@ The uncompromising code formatter ================================= -By using *Black*, you agree to cease control over minutiae of + âAny color you like.â + +By using *Black*, you agree to cede control over minutiae of hand-formatting. In return, *Black* gives you speed, determinism, and freedom from `pycodestyle` nagging about formatting. You will save time and mental energy for more important matters. @@ -14,19 +16,41 @@ possible. Blackened code looks the same regardless of the project you're reading. Formatting becomes transparent after a while and you can focus on the content instead. -.. note:: +Try it out now using the `Black Playground <https://black.vercel.app>`_. - `Black is an early pre-release <installation_and_usage.html#note-this-is-an-early-pre-release>`_. +.. admonition:: Note - Black is now stable! + *Black* is `successfully used <https://github.com/psf/black#used-by>`_ by + many projects, small and big. *Black* has a comprehensive test suite, with efficient + parallel tests, our own auto formatting and parallel Continuous Integration runner. + Now that we have become stable, you should not expect large formatting to changes in + the future. Stylistic changes will mostly be responses to bug reports and support for new Python + syntax. + + Also, as a safety measure which slows down processing, *Black* will check that the + reformatted code still produces a valid AST that is effectively equivalent to the + original (see the + `Pragmatism <./the_black_code_style/current_style.html#pragmatism>`_ + section for details). If you're feeling confident, use ``--fast``. + +.. note:: + :doc:`Black is licensed under the MIT license <license>`. Testimonials ------------ +**Mike Bayer**, author of `SQLAlchemy <https://www.sqlalchemy.org/>`_: + + *I can't think of any single tool in my entire programming career that has given me a + bigger productivity increase by its introduction. I can now do refactorings in about + 1% of the keystrokes that it would have taken me previously when we had no way for + code to format itself.* + **Dusty Phillips**, `writer <https://smile.amazon.com/s/ref=nb_sb_noss?url=search-alias%3Daps&field-keywords=dusty+phillips>`_: *Black is opinionated so you don't have to be.* -**Hynek Schlawack**, creator of `attrs <http://www.attrs.org/>`_, core +**Hynek Schlawack**, creator of `attrs <https://www.attrs.org/>`_, core developer of Twisted and CPython: *An auto-formatter that doesn't suck is all I want for Xmas!* @@ -40,25 +64,68 @@ and `pipenv <https://docs.pipenv.org/>`_: *This vastly improves the formatting of our code. Thanks a ton!* + +Show your style +--------------- + +Use the badge in your project's README.md: + +.. code-block:: md + + [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) + + +Using the badge in README.rst: + +.. code-block:: rst + + .. image:: https://img.shields.io/badge/code%20style-black-000000.svg + :target: https://github.com/psf/black + +Looks like this: + +.. image:: https://img.shields.io/badge/code%20style-black-000000.svg + :target: https://github.com/psf/black + Contents -------- +.. toctree:: + :maxdepth: 3 + :includehidden: + + the_black_code_style/index + +.. toctree:: + :maxdepth: 3 + :includehidden: + :caption: User Guide + + getting_started + usage_and_configuration/index + integrations/index + guides/index + faq + .. toctree:: :maxdepth: 2 + :includehidden: + :caption: Development - installation_and_usage - the_black_code_style - editor_integration - version_control_integration - ignoring_non_modified_files - contributing + contributing/index change_log - reference/reference_summary authors +.. toctree:: + :hidden: + :caption: Project Links + + GitHub <https://github.com/psf/black> + PyPI <https://pypi.org/project/black> + Chat <https://discord.gg/RtVdv86PrH> + Indices and tables ================== * :ref:`genindex` -* :ref:`modindex` * :ref:`search`