Improve docs sharing for docker_compose_v2* modules; fix examples and return docs for docker_compose_v2_pull (#761)

* Move more common documentation to docs fragment.

* Fix examples and return values for docker_compose_v2_pull.

* Remove ignore.

plugins/doc_fragments/compose_v2.py

@@ -35,4 +35,19 @@ options:
           - Equivalent to C(docker compose --profile).
         type: list
         elements: str
+notes:
+  - |-
+    The Docker compose CLI plugin has no stable output format (see for example U(https://github.com/docker/compose/issues/10872)),
+    and for the main operations also no machine friendly output format. The module tries to accomodate this with various
+    version-dependent behavior adjustments and with testing older and newer versions of the Docker compose CLI plugin.
+
+    Currently the module is tested with multiple plugin versions between 2.18.1 and 2.23.3. The exact list of plugin versions
+    will change over time. New releases of the Docker compose CLI plugin can break this module at any time.
+'''
+
+    # The following needs to be kept in sync with the compose_v2 module utils
+    MINIMUM_VERSION = r'''
+options: {}
+requirements:
+  - "Docker CLI with Docker compose plugin 2.18.0 or later"
 '''

plugins/module_utils/compose_v2.py

@@ -166,6 +166,9 @@ _RE_SKIPPED_EVENT = re.compile(
     r'$'
 )
 
+# The following needs to be kept in sync with the MINIMUM_VERSION compose_v2 docs fragment
+MINIMUM_COMPOSE_VERSION = '2.18.0'
+
 
 def _extract_event(line):
     match = _RE_RESOURCE_EVENT.match(line)
@@ -410,7 +413,7 @@ def combine_text_output(*outputs):
 
 
 class BaseComposeManager(DockerBaseClass):
-    def __init__(self, client, min_version='2.18.0'):
+    def __init__(self, client, min_version=MINIMUM_COMPOSE_VERSION):
         super(BaseComposeManager, self).__init__()
         self.client = client
         self.check_mode = self.client.check_mode

plugins/modules/docker_compose_v2.py

@@ -23,6 +23,7 @@ description:
 
 extends_documentation_fragment:
   - community.docker.compose_v2
+  - community.docker.compose_v2.minimum_version
   - community.docker.docker.cli_documentation
   - community.docker.attributes
   - community.docker.attributes.actiongroup_docker
@@ -117,23 +118,12 @@ options:
     type: list
     elements: str
 
-requirements:
-  - "Docker CLI with Docker compose plugin 2.18.0 or later"
-
 author:
   - Felix Fontein (@felixfontein)
 
-notes:
-  - |-
-    The Docker compose CLI plugin has no stable output format (see for example U(https://github.com/docker/compose/issues/10872)),
-    and for the main operations also no machine friendly output format. The module tries to accomodate this with various
-    version-dependent behavior adjustments and with testing older and newer versions of the Docker compose CLI plugin.
-
-    Currently the module is tested with multiple plugin versions between 2.18.1 and 2.23.3. The exact list of plugin versions
-    will change over time. New releases of the Docker compose CLI plugin can break this module at any time.
-
 seealso:
   - module: community.docker.docker_compose
+  - module: community.docker.docker_compose_v2_pull
 '''
 
 EXAMPLES = '''
@@ -400,12 +390,9 @@ from ansible_collections.community.docker.plugins.module_utils.compose_v2 import
 )
 
 
-DOCKER_COMPOSE_MINIMAL_VERSION = '2.18.0'
-
-
 class ServicesManager(BaseComposeManager):
     def __init__(self, client):
-        super(ServicesManager, self).__init__(client, min_version=DOCKER_COMPOSE_MINIMAL_VERSION)
+        super(ServicesManager, self).__init__(client)
         parameters = self.client.module.params
 
         self.state = parameters['state']

plugins/modules/docker_compose_v2_pull.py

@@ -21,6 +21,7 @@ description:
 
 extends_documentation_fragment:
   - community.docker.compose_v2
+  - community.docker.compose_v2.minimum_version
   - community.docker.docker.cli_documentation
   - community.docker.attributes
   - community.docker.attributes.actiongroup_docker
@@ -43,232 +44,20 @@ options:
       - missing
     default: always
 
-requirements:
-  - "Docker CLI with Docker compose plugin 2.18.0 or later"
-
 author:
   - Felix Fontein (@felixfontein)
 
-notes:
-  - |-
-    The Docker compose CLI plugin has no stable output format (see for example U(https://github.com/docker/compose/issues/10872)),
-    and for the main operations also no machine friendly output format. The module tries to accomodate this with various
-    version-dependent behavior adjustments and with testing older and newer versions of the Docker compose CLI plugin.
-
-    Currently the module is tested with multiple plugin versions between 2.18.1 and 2.23.3. The exact list of plugin versions
-    will change over time. New releases of the Docker compose CLI plugin can break this module at any time.
-
 seealso:
-  - module: community.docker.docker_compose
+  - module: community.docker.docker_compose_v2
 '''
 
 EXAMPLES = '''
-# Examples use the django example at https://docs.docker.com/compose/django. Follow it to create the
+- name: Pull images for flask project
-# flask directory
+  community.docker.docker_compose_v2_pull:
-
+    project_src: /path/to/flask
-- name: Run using a project directory
-  hosts: localhost
-  gather_facts: false
-  tasks:
-    - name: Tear down existing services
-      community.docker.docker_compose_v2:
-        project_src: flask
-        state: absent
-
-    - name: Create and start services
-      community.docker.docker_compose_v2:
-        project_src: flask
-      register: output
-
-    - name: Show results
-      ansible.builtin.debug:
-        var: output
-
-    - name: Run `docker-compose up` again
-      community.docker.docker_compose_v2:
-        project_src: flask
-      register: output
-
-    - name: Show results
-      ansible.builtin.debug:
-        var: output
-
-    - ansible.builtin.assert:
-        that: not output.changed
-
-    - name: Stop all services
-      community.docker.docker_compose_v2:
-        project_src: flask
-        state: stopped
-      register: output
-
-    - name: Show results
-      ansible.builtin.debug:
-        var: output
-
-    - name: Verify that web and db services are not running
-      ansible.builtin.assert:
-        that:
-          - "not output.services.web.flask_web_1.state.running"
-          - "not output.services.db.flask_db_1.state.running"
-
-    - name: Restart services
-      community.docker.docker_compose_v2:
-        project_src: flask
-        state: restarted
-      register: output
-
-    - name: Show results
-      ansible.builtin.debug:
-        var: output
-
-    - name: Verify that web and db services are running
-      ansible.builtin.assert:
-        that:
-          - "output.services.web.flask_web_1.state.running"
-          - "output.services.db.flask_db_1.state.running"
 '''
 
 RETURN = '''
-containers:
-  description:
-    - A list of containers associated to the service.
-  returned: success
-  type: list
-  elements: dict
-  contains:
-    Command:
-      description:
-        - The container's command.
-      type: raw
-    CreatedAt:
-      description:
-        - The timestamp when the container was created.
-      type: str
-      sample: "2024-01-02 12:20:41 +0100 CET"
-    ExitCode:
-      description:
-        - The container's exit code.
-      type: int
-    Health:
-      description:
-        - The container's health check.
-      type: raw
-    ID:
-      description:
-        - The container's ID.
-      type: str
-      sample: "44a7d607219a60b7db0a4817fb3205dce46e91df2cb4b78a6100b6e27b0d3135"
-    Image:
-      description:
-        - The container's image.
-      type: str
-    Labels:
-      description:
-        - Labels for this container.
-      type: dict
-    LocalVolumes:
-      description:
-        - The local volumes count.
-      type: str
-    Mounts:
-      description:
-        - Mounts.
-      type: str
-    Name:
-      description:
-        - The container's primary name.
-      type: str
-    Names:
-      description:
-        - List of names of the container.
-      type: list
-      elements: str
-    Networks:
-      description:
-        - List of networks attached to this container.
-      type: list
-      elements: str
-    Ports:
-      description:
-        - List of port assignments as a string.
-      type: str
-    Publishers:
-      description:
-        - List of port assigments.
-      type: list
-      elements: dict
-      contains:
-        URL:
-          description:
-            - Interface the port is bound to.
-          type: str
-        TargetPort:
-          description:
-            - The container's port the published port maps to.
-          type: int
-        PublishedPort:
-          description:
-            - The port that is published.
-          type: int
-        Protocol:
-          description:
-            - The protocol.
-          type: str
-          choices:
-            - tcp
-            - udp
-    RunningFor:
-      description:
-        - Amount of time the container runs.
-      type: str
-    Service:
-      description:
-        - The name of the service.
-      type: str
-    Size:
-      description:
-        - The container's size.
-      type: str
-      sample: "0B"
-    State:
-      description:
-        - The container's state.
-      type: str
-      sample: running
-    Status:
-      description:
-        - The container's status.
-      type: str
-      sample: Up About a minute
-images:
-  description:
-    - A list of images associated to the service.
-  returned: success
-  type: list
-  elements: dict
-  contains:
-    ID:
-      description:
-        - The image's ID.
-      type: str
-      sample: sha256:c8bccc0af9571ec0d006a43acb5a8d08c4ce42b6cc7194dd6eb167976f501ef1
-    ContainerName:
-      description:
-        - Name of the conainer this image is used by.
-      type: str
-    Repository:
-      description:
-        - The repository where this image belongs to.
-      type: str
-    Tag:
-      description:
-        - The tag of the image.
-      type: str
-    Size:
-      description:
-        - The image's size in bytes.
-      type: int
 actions:
   description:
     - A list of actions that have been applied.
@@ -282,12 +71,8 @@ actions:
       type: str
       sample: container
       choices:
-        - container
         - image
-        - network
-        - service
         - unknown
-        - volume
     id:
       description:
         - The ID of the resource that was changed.
@@ -297,16 +82,8 @@ actions:
       description:
         - The status change that happened.
       type: str
-      sample: Creating
+      sample: Pulling
       choices:
-        - Starting
-        - Exiting
-        - Restarting
-        - Creating
-        - Stopping
-        - Killing
-        - Removing
-        - Recreating
         - Pulling
 '''
 
@@ -327,12 +104,9 @@ from ansible_collections.community.docker.plugins.module_utils.compose_v2 import
 from ansible_collections.community.docker.plugins.module_utils.version import LooseVersion
 
 
-DOCKER_COMPOSE_MINIMAL_VERSION = '2.18.0'
-
-
 class PullManager(BaseComposeManager):
     def __init__(self, client):
-        super(PullManager, self).__init__(client, min_version=DOCKER_COMPOSE_MINIMAL_VERSION)
+        super(PullManager, self).__init__(client)
         parameters = self.client.module.params
 
         self.policy = parameters['policy']

tests/sanity/ignore-2.13.txt

@@ -1,4 +1,3 @@
 .azure-pipelines/scripts/publish-codecov.py replace-urlopen
 plugins/modules/docker_compose_v2.py validate-modules:return-syntax-error
-plugins/modules/docker_compose_v2_pull.py validate-modules:return-syntax-error
 plugins/modules/docker_container_copy_into.py validate-modules:undocumented-parameter # _max_file_size_for_diff is used by the action plugin