Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add black-primer docs #1427

Merged
merged 4 commits into from
May 18, 2020
Merged

Add black-primer docs #1427

merged 4 commits into from
May 18, 2020

Conversation

cooperlees
Copy link
Collaborator

@cooperlees cooperlees commented May 17, 2020 •
edited
Loading

  • Document the idea, CLI args, config and a example run for black-primer in README.md
  • Add to docs/index.rst

Addresses #1390

@cooperlees
Add black-primer docs
5627e72 
- Document the idea, CLI args, config and a example run for `black-primer` in README.md
- Add to docs/index.rst
@cooperlees cooperlees added the T: documentation Improvements to the docs (e.g. new topic, correction, etc) label May 17, 2020
@cooperlees cooperlees requested review from ambv and zsol May 17, 2020 20:45
JelleZijlstra
JelleZijlstra reviewed May 17, 2020
View reviewed changes
README.md Outdated Show resolved Hide resolved
README.md Show resolved Hide resolved
README.md Show resolved Hide resolved
@cooperlees
Copy link
Collaborator Author

Thanks - I am the typo king :(

hugovk
hugovk reviewed May 18, 2020
View reviewed changes
Copy link
Contributor

@hugovk hugovk left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Some little suggestions

README.md Outdated
@@ -52,7 +53,7 @@ run but you can reformat Python 2 code with it, too.

To get started right away with sensible defaults:

```
```console
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

```console is best when you start with a $ and have output to show.

Otherwise, use something like ```bash or ```sh

Suggested change
```console
```bash

README.md Outdated
@@ -1068,7 +1069,7 @@ Options:
There is no official blackd client tool (yet!). You can test that blackd is working
using `curl`:

```
```console
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
```console
```bash

README.md Outdated
@@ -1117,6 +1118,124 @@ Apart from the above, `blackd` can produce the following response codes:
The response headers include a `X-Black-Version` header containing the version of
_Black_.

## black-primer

`black-primer` is a tool built for CI (and humans) to have black `--check` a number of
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
`black-primer` is a tool built for CI (and humans) to have black `--check` a number of
`black-primer` is a tool built for CI (and humans) to have _Black_ `--check` a number of

README.md Outdated

`black-primer` is a tool built for CI (and humans) to have black `--check` a number of
(configured in `primer.json`) Git accessible projects in parallel. _(A PR will be
accepted to add hg support)_.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
accepted to add hg support)_.
accepted to add Mercurial support.)_

README.md Outdated

- Ensure we have a `black` + `git` in PATH
- Load projects from `primer.json`
- Run projects in parallel with `--worker` workers (defaults to CPU Count / 2)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- Run projects in parallel with `--worker` workers (defaults to CPU Count / 2)
- Run projects in parallel with `--worker` workers (defaults to CPU count / 2)

README.md Outdated
{
"projects": {
"00_Example": {
"cli_arguments": "List of extra CLI arguments to pass black for this project",
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
"cli_arguments": "List of extra CLI arguments to pass black for this project",
"cli_arguments": "List of extra CLI arguments to pass Black for this project",

README.md Outdated
"projects": {
"00_Example": {
"cli_arguments": "List of extra CLI arguments to pass black for this project",
"expect_formatting_changes": "Boolean to indicate that the version of black is expected to cause changes",
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
"expect_formatting_changes": "Boolean to indicate that the version of black is expected to cause changes",
"expect_formatting_changes": "Boolean to indicate that the version of Black is expected to cause changes",

README.md Outdated
"00_Example": {
"cli_arguments": "List of extra CLI arguments to pass black for this project",
"expect_formatting_changes": "Boolean to indicate that the version of black is expected to cause changes",
"git_clone_url": "URL you would pass `git clone` to checkout this repo",
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
"git_clone_url": "URL you would pass `git clone` to checkout this repo",
"git_clone_url": "URL you would pass `git clone` to check out this repo",

README.md Outdated
"expect_formatting_changes": "Boolean to indicate that the version of black is expected to cause changes",
"git_clone_url": "URL you would pass `git clone` to checkout this repo",
"long_checkout": "Boolean to have repo skipped by defauult unless `--long-checkouts` is specified",
"py_versions": "List of major Python versions to run this project with - all will do as you'd expect - Run on ALL versions"
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
"py_versions": "List of major Python versions to run this project with - all will do as you'd expect - Run on ALL versions"
"py_versions": "List of major Python versions to run this project with - all will do as you'd expect - run on ALL versions"

README.md Outdated
}
```

### Example Run
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
### Example Run
### Example run

@zsol
Copy link
Collaborator

zsol commented May 18, 2020

Content lgtm. I was wondering if we should break up the massive readme and move these additional tools (along with blackd) into separate doc files linked to from the main one. Wdyt?

@cooperlees
Copy link
Collaborator Author

Sure, I would prefer that too. But I feel that’s a different PR where no content changes and also think we should design it together to avoid PR churn?

@zsol
Copy link
Collaborator

zsol commented May 18, 2020 via email

@cooperlees cooperlees merged commit b0f3798 into master May 18, 2020
@cooperlees cooperlees deleted the primer_docs branch May 18, 2020 14:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@JelleZijlstra JelleZijlstra JelleZijlstra left review comments

@hugovk hugovk hugovk left review comments

@ambv ambv Awaiting requested review from ambv

@zsol zsol Awaiting requested review from zsol

Assignees
No one assigned
Labels
T: documentation Improvements to the docs (e.g. new topic, correction, etc)
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
4 participants
@cooperlees @zsol @JelleZijlstra @hugovk