Put services keyword into new format

doc/ci/services/index.md

@@ -259,7 +259,7 @@ test:
 | `name`       | yes, when used with any other option  | 9.4 | Full name of the image to use. If the full image name includes a registry hostname, use the `alias` option to define a shorter service access name. For more information, see [Accessing the services](#accessing-the-services). |
 | `entrypoint` | no     | 9.4 |Command or script to execute as the container's entrypoint. It's translated to Docker's `--entrypoint` option while creating the container. The syntax is similar to [`Dockerfile`'s `ENTRYPOINT`](https://docs.docker.com/engine/reference/builder/#entrypoint) directive, where each shell token is a separate string in the array. |
 | `command`    | no       | 9.4 |Command or script that should be used as the container's command. It's translated to arguments passed to Docker after the image's name. The syntax is similar to [`Dockerfile`'s `CMD`](https://docs.docker.com/engine/reference/builder/#cmd) directive, where each shell token is a separate string in the array. |
-| `alias` (1)     | no       | 9.4 |Additional alias that can be used to access the service from the job's container. Read [Accessing the services](#accessing-the-services) for more information. |
+| `alias` (1)     | no       | 9.4 | Additional alias that can be used to access the service from the job's container. Read [Accessing the services](#accessing-the-services) for more information. |
 | `variables`     | no       | 14.5 | Additional environment variables that are passed exclusively to the service. The syntax is the same as [Job Variables](../variables/index.md). |
 
 (1) Alias support for the Kubernetes executor was [introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/2229) in GitLab Runner 12.8, and is only available for Kubernetes version 1.7 or later.

doc/ci/yaml/index.md

@@ -734,37 +734,50 @@ image:
 
 #### `services`
 
-Use `services` to specify a [service Docker image](../services/index.md), linked to a base image specified in [`image`](#image).
+Use `services` to specify an additional Docker image to run scripts in. The [`services` image](../services/index.md) is linked
+to the image specified in the [`image`](#image) keyword.
 
-For:
-
-- Usage examples, see [Define `services` in the `.gitlab-ci.yml` file](../services/index.md#define-services-in-the-gitlab-ciyml-file).
-- Detailed usage information, refer to [Docker integration](../docker/index.md) documentation.
-- Example services, see [GitLab CI/CD Services](../services/index.md).
-
-##### `services:name`
-
-An [extended Docker configuration option](../docker/using_docker_images.md#extended-docker-configuration-options).
+**Keyword type**: Job keyword. You can use it only as part of a job or in the
+[`default:` section](#custom-default-keyword-values).
 
-For more information, see [Available settings for `services`](../services/index.md#available-settings-for-services).
+**Possible inputs**: The name of the services image, including the registry path if needed, in one of these formats:
 
-##### `services:alias`
+- `<image-name>` (Same as using `<image-name>` with the `latest` tag)
+- `<image-name>:<tag>`
+- `<image-name>@<digest>`
 
-An [extended Docker configuration option](../docker/using_docker_images.md#extended-docker-configuration-options).
+**Example of `services`**:
 
-For more information, see [Available settings for `services`](../services/index.md#available-settings-for-services).
+```yaml
+default:
+  image:
+    name: ruby:2.6
+    entrypoint: ["/bin/bash"]
 
-##### `services:entrypoint`
+  services:
+    - name: my-postgres:11.7
+      alias: db-postgres
+      entrypoint: ["/usr/local/bin/db-postgres"]
+      command: ["start"]
 
-An [extended Docker configuration option](../docker/using_docker_images.md#extended-docker-configuration-options).
+  before_script:
+    - bundle install
 
-For more information, see [Available settings for `services`](../services/index.md#available-settings-for-services).
+test:
+  script:
+    - bundle exec rake spec
+```
 
-##### `services:command`
+In this example, the job launches a Ruby container. Then, from that container, the job launches
+another container that's running PostgreSQL. Then the job then runs scripts
+in that container.
 
-An [extended Docker configuration option](../docker/using_docker_images.md#extended-docker-configuration-options).
+**Related topics**:
 
-For more information, see [Available settings for `services`](../services/index.md#available-settings-for-services).
+- [Available settings for `services`](../services/index.md#available-settings-for-services).
+- [Define `services` in the `.gitlab-ci.yml` file](../services/index.md#define-services-in-the-gitlab-ciyml-file).
+- [Run your CI/CD jobs in Docker containers](../docker/using_docker_images.md).
+- [Use Docker to build Docker images](../docker/using_docker_build.md).
 
 ### `script`
 

doc/user/packages/container_registry/index.md

@@ -309,7 +309,7 @@ in addition to the steps in the
 [Docker-in-Docker](../../../ci/docker/using_docker_build.md#use-the-docker-executor-with-the-docker-image-docker-in-docker) section:
 
 1. Update the `image` and `service` to point to your registry.
-1. Add a service [alias](../../../ci/yaml/index.md#servicesalias).
+1. Add a service [alias](../../../ci/services/index.md#available-settings-for-services).
 
 Below is an example of what your `.gitlab-ci.yml` should look like:
 
@@ -339,7 +339,7 @@ in addition to the steps in the
 [Docker-in-Docker](../../../ci/docker/using_docker_build.md#use-the-docker-executor-with-the-docker-image-docker-in-docker) section:
 
 1. Update the `image` and `service` to point to your registry.
-1. Add a service [alias](../../../ci/yaml/index.md#servicesalias).
+1. Add a service [alias](../../../ci/services/index.md#available-settings-for-services).
 
 Below is an example of what your `.gitlab-ci.yml` should look like: