Update validation README.md

validation/README.md

@@ -103,27 +103,61 @@ $
 Calling the validation tool (almost) stays the same, it just needs instructions to start the Docker container as a prefix:
 
 ```bash
-$ docker run --rm -v /home/user/models:/data registry.scicore.unibas.ch/schwede/mabakerimport/mmcif-dict-suite:latest validate-mmcif-file /data/model.cif
+$ docker run --rm -v /home/user/models:/data registry.scicore.unibas.ch/schwede/modelcif-converters/mmcif-dict-suite:latest validate-mmcif-file /data/model.cif
 {"cifcheck-errors":[],"status":"completed","diagnosis":[],"versions":[{"title":"mmcif_pdbx_v50.dic","version":"5.361","location":"https://raw.github.com/ihmwg/ModelCIF/master/base/mmcif_pdbx_v50.dic"},{"title":"mmcif_ma.dic","version":"1.4.3","location":"https://raw.github.com/ihmwg/ModelCIF/master/archive/mmcif_ma-v1.4.3.dic"}]}
 $ 
 ```
 
-- [`docker run`](https://docs.docker.com/engine/reference/commandline/run/) starts a new Docker container from image `registry.scicore.unibas.ch/schwede/mabakerimport/mmcif-dict-suite:latest` and executes the `validate-mmcif-file` command inside the container.
+- [`docker run`](https://docs.docker.com/engine/reference/commandline/run/) starts a new Docker container from image `registry.scicore.unibas.ch/schwede/modelcif-converters/mmcif-dict-suite:latest` and executes the `validate-mmcif-file` command inside the container.
 - `--rm` makes sure that the container is removed from the system once the job completed.
 - `-v` mounts directory `/home/user/models` from the local host computer to `/data` inside the Docker container, otherwise the `validate-mmcif-file` command has no access to local files. This makes the ModelCIF file `/home/user/models/model.cif` available as `/data/model.cif` to commands executed by `docker run`. Keep in mind, `validate-mmcif-file -e` and `validate-mmcif-file -a` also need to refer to `/data` (or any other local directory mounted in the Docker container).
 
 
 ## How to get the Docker container
 
+Before running the Docker container, you need a local copy of its image. There are three ways to get it:
+
+- `docker run` will pull it automatically upon first call
+- [`docker pull`](https://docs.docker.com/engine/reference/commandline/pull/) the Docker image yourself before running it
+- [`docker build`](https://docs.docker.com/engine/reference/commandline/build/) the image from scratch
+
+
 ### How to pull a copy of the Docker container from our registry
 
-- since we use it ourselves and are involved in the development, we usually notice when a new dictionary comes out
+With `docker pull`, the ready-made Docker image can be fetched from our [Docker registry](https://git.scicore.unibas.ch/schwede/modelcif-converters/container_registry/). Two kinds of Docker images available, differentiated by tags. The `latest` tag refers to the Docker image with the most recent ModelCIF dictionary. This should be the default choice. For specific use cases, e.g. debugging, we also provide Docker images for older versions of the ModelCIF dictionary, those are tagged with the version number of the dictionary. The `latest` image is pulled like this:
+
+```terminal
+$ docker pull registry.scicore.unibas.ch/schwede/modelcif-converters/mmcif-dict-suite:latest
+```
+
 
 ### How to build the Docker container from scratch
 
+Here is the command we use to generate the Docker image. It works when executed from within the [`validation/`](./validation) subdirectory of the [Git repository](https://git.scicore.unibas.ch/schwede/modelcif-converters):
+
+```terminal
+docker build -t registry.scicore.unibas.ch/schwede/modelcif-converters/mmcif-dict-suite:latest .
+```
+
+When developing you own tools using the Docker image, there is one [build argument](https://docs.docker.com/engine/reference/commandline/build/#set-build-time-variables---build-arg) that adds an [editor](https://www.gnu.org/software/emacs/, [Black](https://black.readthedocs.io/en/stable/), [Pylint](https://pylint.org) and [bash](https://tiswww.case.edu/php/chet/bash/bashtop.html) to ease working in interactive sessions inside the Docker container:
+
+```terminal
+docker build --build-arg ADD_DEV=yes -t registry.scicore.unibas.ch/schwede/modelcif-converters/mmcif-dict-suite:dev .
+```
+
+The [`pyproject.toml`](../pyproject.toml) we use can be found in Git repository root.
 
 # Files in this directory
 
+|Path       |Content                                                         |
+|-----------|----------------------------------------------------------------|
+|[Dockerfile](./Dockerfile)|Build instructions for the Docker image|
+|[README.md](./README.md)|This README|
+|[entrypoint.sh](./entrypoint.sh)|Script executed on Docker container start|
+|[get-mmcif-dict-versions.py](./get-mmcif-dict-versions.py)|Extract versions of mmCIF dictionaries, used for building the Docker image. Copied into the image as `get-mmcif-dict-versions.py`.|
+|[validate-mmcif-file.py](./validate-mmcif-file.py)|Validation tool, copied into the image as `validate-mmcif-file`.|
+
 <!--  LocalWords:  PDBx ModelCIF TOC JSON CifCheck RCSB mmcif cif pdbx dic dir
-      LocalWords:  url pae sdb SDB stdout modelcif cifcheck
+      LocalWords:  url pae sdb SDB stdout modelcif cifcheck arg Pylint DEV md
+      LocalWords:  pyproject toml README entrypoint py
  -->