From 1d7163957a34e8f071aaf9ac59467b912449fb07 Mon Sep 17 00:00:00 2001 From: pszlazak Date: Tue, 16 Nov 2021 03:47:21 +0100 Subject: [PATCH] Docker image usage description (#2412) Co-authored-by: Jelle Zijlstra --- .../black_docker_image.md | 46 +++++++++++++++++++ docs/usage_and_configuration/index.rst | 2 + 2 files changed, 48 insertions(+) create mode 100644 docs/usage_and_configuration/black_docker_image.md diff --git a/docs/usage_and_configuration/black_docker_image.md b/docs/usage_and_configuration/black_docker_image.md new file mode 100644 index 0000000..0a45843 --- /dev/null +++ b/docs/usage_and_configuration/black_docker_image.md @@ -0,0 +1,46 @@ +# Black Docker image + +Official _Black_ Docker images are available on Docker Hub: +https://hub.docker.com/r/pyfound/black + +_Black_ images with the following tags are available: + +- release numbers, e.g. `21.5b2`, `21.6b0`, `21.7b0` etc.\ + ℹ Recommended for users who want to use a particular version of _Black_. +- `latest_release` - tag created when a new version of _Black_ is released.\ + ℹ Recommended for users who want to use released versions of _Black_. It maps to [the latest release](https://github.com/psf/black/releases/latest) + of _Black_. +- `latest` - tag used for the newest image of _Black_.\ + ℹ Recommended for users who always want to use the latest version of _Black_, even before + it is released. + +There is one more tag used for _Black_ Docker images - `latest_non_release`. It is +created for all unreleased +[commits on the `main` branch](https://github.com/psf/black/commits/main). This tag is +not meant to be used by external users. + +## Usage + +A permanent container doesn't have to be created to use _Black_ as a Docker image. It's +enough to run _Black_ commands for the chosen image denoted as `:tag`. In the below +examples, the `latest_release` tag is used. If `:tag` is omitted, the `latest` tag will +be used. + +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 +``` + +### Check code + +```console +$ docker run --rm --volume $(pwd):/src --workdir /src pyfound/black:latest_release black --check . +``` + +_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 also be considered. diff --git a/docs/usage_and_configuration/index.rst b/docs/usage_and_configuration/index.rst index 84a9c0c..f6152ee 100644 --- a/docs/usage_and_configuration/index.rst +++ b/docs/usage_and_configuration/index.rst @@ -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 @@ -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 ` - :doc:`Black as a server (blackd) <./black_as_a_server>` +- :doc:`Black Docker image <./black_docker_image>` -- 2.39.5