Formalise style preference description (#2818)

[etc/vim.git] / docs / index.rst

diff --git a/docs/index.rst b/docs/index.rst
index 9422402956649b5903df3167e456341d1c50f22c..8a8da0d6127e45137082cd8eb118571e1e8c9cc2 100644 (file)
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -4,7 +4,9 @@
 The uncompromising code formatter
 =================================
 
 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.
 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.
 
 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
 ------------
 
 
 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.*
 
 **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!*
 developer of Twisted and CPython:
 
    *An auto-formatter that doesn't suck is all I want for Xmas!*


@@ -40,23 +64,68 @@ and `pipenv <https://docs.pipenv.org/>`_:
 
    *This vastly improves the formatting of our code. Thanks a ton!*
 
 
    *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
 --------
 
 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
 .. toctree::
    :maxdepth: 2

+   :includehidden:
+   :caption: Development

 
 

-   installation_and_usage
-   the_black_code_style
-   editor_integration
-   contributing
+   contributing/index

    change_log
    authors
 
    change_log
    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`
 
 Indices and tables
 ==================
 
 * :ref:`genindex`

-* :ref:`modindex`

 * :ref:`search`
 * :ref:`search`