X-Git-Url: https://git.madduck.net/etc/vim.git/blobdiff_plain/489d00ed8f4fb90d5788609a474632ab5a16591f..b97a4ac449c6f0fd987e9ad2d0228fa756870086:/docs/index.rst?ds=inline diff --git a/docs/index.rst b/docs/index.rst index da60f7b..1515697 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -14,19 +14,43 @@ 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>`_. + +.. admonition:: Note - this is a beta product - `Black is beta <installation_and_usage.html#note-this-is-a-beta-product>`_. + *Black* is already `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. + However, *Black* is still beta. Things will probably be wonky for a while. This is + made explicit by the "Beta" trove classifier, as well as by the "b" in the version + number. What this means for you is that **until the formatter becomes stable, you + should expect some formatting to change in the future**. That being said, no drastic + stylistic changes are planned, mostly responses to bug reports. + 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,27 +64,65 @@ 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: 2 - - installation_and_usage - the_black_code_style - pyproject_toml - editor_integration - version_control_integration - ignoring_unmodified_files - contributing - show_your_style + :maxdepth: 3 + :includehidden: + + the_black_code_style/index + +.. toctree:: + :maxdepth: 3 + :includehidden: + + getting_started + usage_and_configuration/index + integrations/index + guides/index + faq + +.. toctree:: + :maxdepth: 3 + :includehidden: + + contributing/index change_log - reference/reference_summary authors +.. toctree:: + :hidden: + + 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`