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鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Docker image usage description #2412

Merged
merged 5 commits into from Nov 16, 2021
Merged

Docker image usage description #2412

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
995e5ac
Docker image usage description
pszlazak Aug 3, 2021
a0e2eaa
Suggestions from code review
pszlazak Aug 7, 2021
bd03bf8
Improved description of tags
pszlazak Aug 7, 2021
e25cafe
Rephrased tags description
pszlazak Aug 9, 2021
99a6553
Applying review suggestions
pszlazak Aug 26, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
40 changes: 40 additions & 0 deletions docs/usage_and_configuration/black_docker_image.md
View file
Open in desktop
@@ -0,0 +1,40 @@
# Black Docker image

Official _Black_ Docker images are available on Docker Hub:
https://hub.docker.com/r/pyfound/black

Following tags are used for _Black_ images:
pszlazak marked this conversation as resolved.
Show resolved Hide resolved

- `latest` - tag used for either
pszlazak marked this conversation as resolved.
Show resolved Hide resolved
[the latest commit of `main` branch](https://github.com/psf/black/commits/main) or
[the latest release](https://github.com/psf/black/releases/latest)
- `latest_release` - tag used for
[the latest release](https://github.com/psf/black/releases/latest)
- `latest_non_release` - tag used for
[the latest commit of `main` branch](https://github.com/psf/black/commits/main)
- release numbers, e.g. `21.5b2`, `21.6b0`, `21.7b0` etc.

## Usage

Permanent container doesn't have to be created for using _Black_ as Docker image. It's
enough to run _Black_ commands for chosen image denoted as `:tag`. In examples below
`latest_release` tag is used. If `:tag` is omitted, `latest` tag will be used.
pszlazak marked this conversation as resolved.
Show resolved Hide resolved

More about _Black_ usage can be found in
[Usage and Configuration: The basics](./the_basics.md).

### Check Black version

```console
$ docker run --rm pyfound/black:latest_release black --version
Copy link
Collaborator

@cooperlees cooperlees Aug 9, 2021 •
edited

Choose a reason for hiding this comment

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

We could state --rm is optional, but not needed I don't think really needed. If I was running black a lot on the box I'd leave the container up and execute out of it. But depends on your use case :)

Suggested change
$ docker run --rm pyfound/black:latest_release black --version
$ docker run [--rm] pyfound/black:latest_release black --version

Copy link
Contributor Author

Choose a reason for hiding this comment

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

@cooperlees - sorry for answering late. I was on vacation with very limited access to the Internet.

I believe Black image is not prepared for constantly running in the background. Nevertheless container can be created with all needed customizations (volume mounting etc.) and started when needed. But it means you have to store your source code always in the same place, so volume mounting works. Or you should have separate container for every place with source code with different volume mounting set.

That's why in provided examples container is removed after command is completed. Of course this is only suggestion.

```

### Check code

```console
$ docker run --rm --volume $(pwd):/src --workdir /src pyfound/black:latest_release black --check .
pszlazak marked this conversation as resolved.
Show resolved Hide resolved
```

_Remark_: besides [regular _Black_ exit codes](./the_basics.md) returned by `--check`
option, [Docker exit codes](https://docs.docker.com/engine/reference/run/#exit-status)
should be also considered.
pszlazak marked this conversation as resolved.
Show resolved Hide resolved
2 changes: 2 additions & 0 deletions docs/usage_and_configuration/index.rst
View file
Open in desktop
Expand Up @@ -7,6 +7,7 @@ Usage and Configuration
the_basics
file_collection_and_discovery
black_as_a_server
black_docker_image

Sometimes, running *Black* with its defaults and passing filepaths to it just won't cut
it. Passing each file using paths will become burdensome, and maybe you would like
Expand All @@ -22,3 +23,4 @@ This section covers features of *Black* and configuring *Black* in detail:
- :doc:`The basics <./the_basics>`
- :doc:`File collection and discovery <file_collection_and_discovery>`
- :doc:`Black as a server (blackd) <./black_as_a_server>`
- :doc:`Black Docker image <./black_docker_image>`