docs/index.rst

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