Improve example in README

[akaihola]

Also point out in a more clear way that the path arguments can be both files and directories.

[markddavidoff]

sure, adding the file(s) helps clarify the current behavior, but i believe darker should also extend black's behavior by letting you pass multiple file paths.

[markddavidoff]

Suggested change

$ mkdir test && cd test && git init

Don't really need this, as it is a given that we will have python files and be in a git directory. instead consider an example showing an error thrown when we are not in a git directory, with a comment re-statating that you need to be in a git directory. Those are often easier to find when people scan the docs while troubleshooting

[akaihola]

What I intended to do in this example is give the reader a complete set of command lines they can copy-paste on the terminal, and have the exact thing described happen on their own disk.

But you have a good point on troubleshooting. I'll try adding that.

[markddavidoff]

For readability, i don't think you should include the code used to generate the examples as they themselves distract away from the actual example. I can't nest backticks in the suggestion block so i'll just make this a comment instead:

our_file.py at commit hash XXXXXXXX

if True: print('hi')

if False: print('there')

An uncommitted change to the our_file.py:

if True: print('changed')

if False: print('there')

Show changes to the file(s) darker would make

Note, the if False: print('there') is omitted as it was not modified!

$ darker --diff ./our_file.py -r XXXXXXXX
> --- test.py
> +++ test.py
> @@ -1,3 +1,4 @@
> -if True: print('changed')
> +if True:
> +    print("changed")

You can also specify all files in the current directory:
all files under the current directory

$ darker --diff . -r XXXXXXXX

Black the file(s) with darker!

$ darker ./our_file.py  -r XXXXXXXX

or

$ darker .  -r XXXXXXXX

Output our blacked file:
Note, the if False: print('there') is not blacked as it was not been modified!

$ cat ./our_file.py
> if True: 
>     print('changed')
> if False: print('there')

[markddavidoff]

@akaihola hopefully you find these suggestions useful, if you'd like i can submit them in another pr

[akaihola]

Yes, this is very useful! I actually wanted to combine your suggestions immediately wtih some of my own ideas – what do you think of the example now?

[akaihola]

One modification to your suggestion was that I didn't want to introduce the -r switch in the very first example – for local interactive use I expect the default comparison to HEAD to be the sane default most often. It's in the CI environment where --revision becomes especially handy.

[akaihola]

sure, adding the file(s) helps clarify the current behavior, but i believe darker should also extend black's behavior by letting you pass multiple file paths.

It does!

You can run

$ darker first.py second.py subdirectory/deep/third.py

[akaihola]

I've been actually dreaming about a screencast. It would be fantastic to show an actual coding session in which some parts of a heavily non-black-formatted repository are edited and interactively reformatted in PyCharm or VS Code using Darker.

Update: See #73.

[akaihola]

By the way @markddavidoff if you're interested to contribute more to Darker, I can invite you as a contributor. You may also be interested in #60 – let us know your time zone and schedules there in case you'd like to meet other contributors on-line.

[markddavidoff]

@akaihola unfortunately, although interested, I can't honestly say I'd be able to make time for any meaningful contributions. Please feel free to adopt my suggestions as you wish!

[akaihola]

@markddavidoff wrote:

Please feel free to adopt my suggestions as you wish!

Ok thanks for all your feedback Mark!

I added other contributors as additional reviewers – I hope someone check how I modified the example in README.rst to give a second opinion and to make sure I didn't miss something.

[CorreyL]

Definitely makes what the example was originally trying to get across much easier to read!