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 **Dusty Phillips**, `writer <https://smile.amazon.com/s/ref=nb_sb_noss?url=search-alias%3Daps&field-keywords=dusty+phillips>`_:
  43
  44    *Black is opinionated so you don't have to be.*
  45
  46 **Hynek Schlawack**, creator of `attrs <https://www.attrs.org/>`_, core
  47 developer of Twisted and CPython:
  48
  49    *An auto-formatter that doesn't suck is all I want for Xmas!*
  50
  51 **Carl Meyer**, `Django <https://www.djangoproject.com/>`_ core developer:
  52
  53    *At least the name is good.*
  54
  55 **Kenneth Reitz**, creator of `requests <http://python-requests.org/>`_
  56 and `pipenv <https://docs.pipenv.org/>`_:
  57
  58    *This vastly improves the formatting of our code. Thanks a ton!*
  59
  60
  61 Show your style
  62 ---------------
  63
  64 Use the badge in your project's README.md:
  65
  66 .. code-block:: md
  67
  68    [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
  69
  70
  71 Using the badge in README.rst:
  72
  73 .. code-block:: rst
  74
  75    .. image:: https://img.shields.io/badge/code%20style-black-000000.svg
  76       :target: https://github.com/psf/black
  77
  78 Looks like this:
  79
  80 .. image:: https://img.shields.io/badge/code%20style-black-000000.svg
  81    :target: https://github.com/psf/black
  82
  83 Contents
  84 --------
  85
  86 .. toctree::
  87    :maxdepth: 3
  88    :includehidden:
  89
  90    the_black_code_style/index
  91
  92 .. toctree::
  93    :maxdepth: 3
  94    :includehidden:
  95
  96    getting_started
  97    usage_and_configuration/index
  98    integrations/index
  99    guides/index
 100    faq
 101
 102 .. toctree::
 103    :maxdepth: 3
 104    :includehidden:
 105
 106    contributing/index
 107    change_log
 108    authors
 109
 110 .. toctree::
 111    :hidden:
 112
 113    GitHub ↪ <https://github.com/psf/black>
 114    PyPI ↪ <https://pypi.org/project/black>
 115    IRC ↪ <https://webchat.freenode.net/?channels=%23blackformatter>
 116
 117 Indices and tables
 118 ==================
 119
 120 * :ref:`genindex`
 121 * :ref:`search`