Docker image usage description (#2412)

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>

diff --git a/docs/usage_and_configuration/black_docker_image.md b/docs/usage_and_configuration/black_docker_image.md
new file mode 100644 (file)
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 84a9c0cb99bfde6a58fdde90813615a023aa64dc..f6152eec90cb0c9486c25c484c047744e30cdbce 100644 (file)
--- 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 <file_collection_and_discovery>`
 - :doc:`Black as a server (blackd) <./black_as_a_server>`
+- :doc:`Black Docker image <./black_docker_image>`