docs/getting_started.md

   1 # Getting Started
   2
   3 New to _Black_? Don't worry, you've found the perfect place to get started!
   4
   5 ## Do you like the _Black_ code style?
   6
   7 Before using _Black_ on some of your code, it might be a good idea to first understand
   8 how _Black_ will format your code. _Black_ isn't for everyone and you may find something
   9 that is a dealbreaker for you personally, which is okay! The current _Black_ code style
  10 [is described here](./the_black_code_style/current_style.md).
  11
  12 ## Try it out online
  13
  14 Also, you can try out _Black_ online for minimal fuss on the
  15 [Black Playground](https://black.vercel.app) generously created by José Padilla.
  16
  17 ## Installation
  18
  19 _Black_ can be installed by running `pip install black`. It requires Python 3.6.2+ to
  20 run, but can format Python 2 code too. Python 2 support needs the `typed_ast`
  21 dependency, which be installed with `pip install black[python2]`. If you want to format
  22 Jupyter Notebooks, install with `pip install black[jupyter]`.
  23
  24 If you can't wait for the latest _hotness_ and want to install from GitHub, use:
  25
  26 `pip install git+git://github.com/psf/black`
  27
  28 ## Basic usage
  29
  30 To get started right away with sensible defaults:
  31
  32 ```sh
  33 black {source_file_or_directory}...
  34 ```
  35
  36 You can run _Black_ as a package if running it as a script doesn't work:
  37
  38 ```sh
  39 python -m black {source_file_or_directory}...
  40 ```
  41
  42 ## Next steps
  43
  44 Took a look at [the _Black_ code style](./the_black_code_style/current_style.md) and
  45 tried out _Black_? Fantastic, you're ready for more. Why not explore some more on using
  46 _Black_ by reading
  47 [Usage and Configuration: The basics](./usage_and_configuration/the_basics.md).
  48 Alternatively, you can check out the
  49 [Introducing _Black_ to your project](./guides/introducing_black_to_your_project.md)
  50 guide.