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 By using *Black*, you agree to cede control over minutiae of
   8 hand-formatting. In return, *Black* gives you speed, determinism, and
   9 freedom from `pycodestyle` nagging about formatting. You will save time
  10 and mental energy for more important matters.
  11
  12 *Black* makes code review faster by producing the smallest diffs
  13 possible. Blackened code looks the same regardless of the project
  14 you're reading. Formatting becomes transparent after a while and you
  15 can focus on the content instead.
  16
  17 Try it out now using the `Black Playground <https://black.vercel.app>`_.
  18
  19 .. admonition:: Note - this is a beta product
  20
  21    *Black* is already `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    However, *Black* is still beta. Things will probably be wonky for a while. This is
  25    made explicit by the "Beta" trove classifier, as well as by the "b" in the version
  26    number. What this means for you is that **until the formatter becomes stable, you
  27    should expect some formatting to change in the future**. That being said, no drastic
  28    stylistic changes are planned, mostly responses to bug reports.
  29
  30    Also, as a safety measure which slows down processing, *Black* will check that the
  31    reformatted code still produces a valid AST that is effectively equivalent to the
  32    original (see the
  33    `Pragmatism <./the_black_code_style/current_style.html#pragmatism>`_
  34    section for details). If you're feeling confident, use ``--fast``.
  35
  36 .. note::
  37    :doc:`Black is licensed under the MIT license <license>`.
  38
  39 Testimonials
  40 ------------
  41
  42 **Mike Bayer**, author of `SQLAlchemy <https://www.sqlalchemy.org/>`_:
  43
  44    *I can't think of any single tool in my entire programming career that has given me a
  45    bigger productivity increase by its introduction. I can now do refactorings in about
  46    1% of the keystrokes that it would have taken me previously when we had no way for
  47    code to format itself.*
  48
  49 **Dusty Phillips**, `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
  54 developer of 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/>`_
  63 and `pipenv <https://docs.pipenv.org/>`_:
  64
  65    *This vastly improves the formatting of our code. Thanks a ton!*
  66
  67
  68 Show your style
  69 ---------------
  70
  71 Use the badge in your project's README.md:
  72
  73 .. code-block:: md
  74
  75    [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
  76
  77
  78 Using the badge in README.rst:
  79
  80 .. code-block:: rst
  81
  82    .. image:: https://img.shields.io/badge/code%20style-black-000000.svg
  83       :target: https://github.com/psf/black
  84
  85 Looks like this:
  86
  87 .. image:: https://img.shields.io/badge/code%20style-black-000000.svg
  88    :target: https://github.com/psf/black
  89
  90 Contents
  91 --------
  92
  93 .. toctree::
  94    :maxdepth: 3
  95    :includehidden:
  96
  97    the_black_code_style/index
  98
  99 .. toctree::
 100    :maxdepth: 3
 101    :includehidden:
 102
 103    getting_started
 104    usage_and_configuration/index
 105    integrations/index
 106    guides/index
 107    faq
 108
 109 .. toctree::
 110    :maxdepth: 3
 111    :includehidden:
 112
 113    contributing/index
 114    change_log
 115    authors
 116
 117 .. toctree::
 118    :hidden:
 119
 120    GitHub ↪ <https://github.com/psf/black>
 121    PyPI ↪ <https://pypi.org/project/black>
 122    IRC ↪ <https://webchat.freenode.net/?channels=%23blackformatter>
 123
 124 Indices and tables
 125 ==================
 126
 127 * :ref:`genindex`
 128 * :ref:`search`