docker docs: remove VirtualBox content and update a few explanations

docs/docker.rst

@@ -41,22 +41,7 @@ The recommended OCRmyPDF Docker image is currently named ``ocrmypdf``:
 
    docker pull jbarlow83/ocrmypdf
 
-
-OCRmyPDF will use all available CPU cores. By default, the VirtualBox
-machine instance on Windows and macOS has only a single CPU core
-enabled. Use the VirtualBox Manager to determine the name of your Docker
-engine host, and then follow these optional steps to enable multiple
-CPUs:
-
-.. code-block:: bash
-
-   # Optional step for Mac OS X users
-   docker-machine stop "yourVM"
-   VBoxManage modifyvm "yourVM" --cpus 2  # or whatever number of core is desired
-   docker-machine start "yourVM"
-   eval $(docker-machine env "yourVM")
-
-See the Docker documentation for
+OCRmyPDF will use all available CPU cores. See the Docker documentation for
 `adjusting memory and CPU on other platforms <https://docs.docker.com/config/containers/resource_constraints/>`__.
 
 Using the Docker image on the command line
@@ -66,6 +51,8 @@ Using the Docker image on the command line
 container is ephemeral – it runs for one OCR job and terminates, just like a
 command line program. We are using Docker to deliver an application (as opposed
 to the more conventional case, where a Docker container runs as a server).
+For that reason we usually use the ``--rm`` argument to delete the container
+when it exits.
 
 To start a Docker container (instance of the image):
 
@@ -116,7 +103,7 @@ Dockerfile based on the public one.
    # Example: add Italian
    RUN apt install tesseract-ocr-ita
 
-To install language packs (training data) such as the 
+To install language packs (training data) such as the
 `tessdata_best <https://github.com/tesseract-ocr/tessdata_best>`_ suite or
 custom data, you first need to determine the version of Tesseract data files, which
 may differ from the Tesseract program version. Use this command to determine the data
@@ -132,17 +119,35 @@ You can then add new data with either a Dockerfile:
 
 .. code-block:: dockerfile
 
-   FROM jbarlow83/ocrmypdf
+   FROM jbarlow83/ocrmypdf:{TAG}
 
    # Example: add a tessdata_best file
    COPY chi_tra_vert.traineddata /usr/share/tesseract-ocr/<data version>/tessdata/
 
+When creating your own image, you should always pin a specific version of the
+OCRmyPDF Docker image. This ensures that your image will not break when a new
+version of OCRmyPDF is released.
+
 Alternately, you can copy training data into a Docker container as follows:
 
 .. code-block:: bash
 
    docker cp mycustomtraining.traineddata name_of_container:/usr/share/tesseract-ocr/<tesseract version>/tessdata/
 
+Extending the Docker image
+==========================
+
+You can extend the Docker image with your own customizations, similar to the way
+it is extended to add language packs.
+
+Note that the Docker image is subject to change at any time. For example, the base
+image may be updated to a newer version of Ubuntu or Debian. Such changes will be
+noted in the release notes but might occur at minor versions releases, unless the
+way a "casual" user of the Docker image is affected.
+
+If you extend the Docker image, you should pin a specific version of the OCRmyPDF
+Docker image.
+
 Executing the test suite
 ========================
 
@@ -150,7 +155,7 @@ The OCRmyPDF test suite is installed with image. To run it:
 
 .. code-block:: bash
 
-   docker run --entrypoint python3  jbarlow83/ocrmypdf -m pytest
+   docker run --rm --entrypoint python3  jbarlow83/ocrmypdf -m pytest
 
 Accessing the shell
 ===================
@@ -171,6 +176,9 @@ service. The webservice may be launched as follows:
 
    docker run --entrypoint python3 -p 5000:5000  jbarlow83/ocrmypdf webservice.py
 
+We omit the ``--rm`` parameter so that the container will not be
+automatically deleted when it exits.
+
 This will configure the machine to listen on port 5000. On Linux machines
 this is port 5000 of localhost. On macOS or Windows machines running
 Docker, this is port 5000 of the virtual machine that runs your Docker