Merge pull request #92 from salsadigitalauorg/feature/DEVOPS-499-docs…

…-improvements

Added docsite generator

.docker/Dockerfile.docs

@@ -0,0 +1,35 @@
+FROM python:3.11-slim
+
+ARG OPERATION=build
+ARG ANSIBLE_COLLECTIONS_PATH=/collections
+ENV ANSIBLE_COLLECTIONS_PATH=${ANSIBLE_COLLECTIONS_PATH}
+
+RUN set -ex; \
+  mkdir -p ${ANSIBLE_COLLECTIONS_PATH}/ansible_collections/lagoon /built-docs; \
+  apt-get update && apt-get install -y rsync; \
+  apt-get clean; \
+  rm -rf /var/lib/apt/lists/*
+
+COPY api ${ANSIBLE_COLLECTIONS_PATH}/ansible_collections/lagoon/api
+
+WORKDIR ${ANSIBLE_COLLECTIONS_PATH}/ansible_collections/lagoon/api
+
+RUN set -ex; \
+  python -m pip install ansible antsibull-docs; \
+  \
+  if [ "${OPERATION}" = "build" ]; then \
+    # Use more lenient linting version - use the stricter one when ready.
+    antsibull-docs lint-collection-docs .; \
+    # antsibull-docs lint-collection-docs --plugin-docs .; \
+    antsibull-docs sphinx-init --use-current \
+      --squash-hierarchy lagoon.api --dest-dir /built-docs; \
+    cd /built-docs; \
+    python -m pip install -r requirements.txt; \
+    ./build.sh; \
+  fi
+
+WORKDIR /built-docs/build/html
+
+EXPOSE 8000
+
+CMD [ "python", "-m", "http.server" ]

.gitignore

@@ -4,3 +4,5 @@ api/tests/output
 
 .docker/mock-server/node_modules
 .docker/mock-server/package-lock.json
+
+built-docs

README.md

@@ -28,3 +28,19 @@ gql-cli https://api.lagoon.amazeeio.cloud/graphql --print-schema \
 docker-compose build
 docker-compose run --rm test units -v --requirements
 ```
+
+## Creating the docs
+
+Linting the docs
+```sh
+docker compose build lint-docs
+docker compose run --rm lint-docs
+```
+
+Build the docs:
+```sh
+docker compose build docs
+docker compose up -d docs
+```
+
+Docs should be ready to browse at [http://localhost:9180](http://localhost:9180).

api/galaxy.yml

@@ -4,14 +4,15 @@ version: 1.3.0
 readme: README.md
 
 authors:
-  - Yusuf Hasan Miyan <yusuf.hasanmiyan@salsadigital.com.au>
-  - Steve Worley <steven.worley@salsadigital.com.au>
+  - Yusuf Hasan Miyan <yusuf.hasanmiyan@salsa.digital>
+  - Steve Worley <steven.worley@salsa.digital>
 
 description: A collection to interact with the Lagoon API
 
 # Either a single license or a list of licenses for content inside of a collection. Ansible Galaxy currently only
 # accepts L(SPDX,https://spdx.org/licenses/) licenses. This key is mutually exclusive with 'license_file'
-license: GPL-2.0-or-later
+license:
+  - GPL-2.0-or-later
 
 # A list of tags you want to associate with the collection for indexing/searching. A tag name has the same character
 # requirements as 'namespace' and 'name'

api/plugins/inventory/lagoon.py

@@ -15,6 +15,8 @@
 
 DOCUMENTATION = """
     name: lagoon
+    short_description: Builds an inventory of Lagoon projects and environments.
+    description: Builds an inventory of Lagoon projects and environments.
     plugin_type: inventory
     extends_documentation_fragment:
         - constructed

api/plugins/modules/deploy_target_config.py

@@ -2,53 +2,53 @@
 # -*- coding: utf-8 -*-
 
 DOCUMENTATION = r'''
----
 module: deploy_target_config
 
 short_description: Manage deploy target configs for a project.
 
 version_added: "1.0.1"
 
 description:
-    - Allows creating, updating, replacing and deleting deploy target configs.
+  - Allows creating, updating, replacing and deleting deploy target configs.
 
 options:
-    project:
-        description: The name of the project.
-        required: true
-        type: str
-    configs:
-        description:
-            - List of config values.
-        required: false
-        type: list
-        elements: dict
-    state:
-        description:
-        - Determines if the configs should be created, updated, or deleted. When set to C(present), the configs will be
-        created, if they do not already exist. If set to C(absent), existing configs will be deleted. If set to
-        C(present), existing configs will be updated, if its attributes differ from those specified using
-        I(configs). If I(replace) is C(true), existing values are deleted and new values are created for the provided
-        configs.
-        type: str
-        default: present
-        choices: [ absent, present ]
-    replace:
-        description:
-        - If set to C(true), and I(state) is C(present), existing configs will be deleted and new ones created.
-        type: bool
-        default: False
+  project:
+    description: The name of the project.
+    required: true
+    type: str
+  configs:
+    description:
+      - List of config values.
+    required: false
+    type: list
+    elements: dict
+  state:
+    description: |
+      Determines if the configs should be created, updated, or deleted. When set to C(present), the configs will be
+      created, if they do not already exist. If set to C(absent), existing configs will be deleted. If set to
+      C(present), existing configs will be updated, if its attributes differ from those specified using
+      I(configs). If I(replace) is C(true), existing values are deleted and new values are created for the provided
+      configs.
+    type: str
+    default: present
+    choices: [ absent, present ]
+  replace:
+      description: |
+        If set to C(true), and I(state) is C(present), existing configs will be deleted and new ones created.
+      type: bool
+      default: False
 
 extends_documentation_fragment:
   - lagoon.api.auth_options
 
 author:
-    - Yusuf Hasan Miyan (@yusufhm)
+  - Yusuf Hasan Miyan (@yusufhm)
 
 seealso:
-    # TODO: Update to official link from docs when available.
-    - name: Lagoon deploy target configs docs
-      link: https://github.com/uselagoon/lagoon/blob/main/docs/using-lagoon-advanced/deploytarget_configs.md
+  # TODO: Update to official link from docs when available.
+  - name: Lagoon deploy target configs docs
+    description: Link to the Lagoon deploy target configs documentation.
+    link: https://github.com/uselagoon/lagoon/blob/main/docs/using-lagoon-advanced/deploytarget_configs.md
 '''
 
 EXAMPLES = r'''

api/plugins/modules/environment.py

@@ -2,7 +2,6 @@
 # -*- coding: utf-8 -*-
 
 DOCUMENTATION = r'''
----
 module: environment
 
 short_description: Manage a project's environments.
@@ -21,7 +20,7 @@
         description: The name of the environment.
         required: true
         type: str
-    definition: (TODO)
+    definition:
         description: Values for the environment creation, as a dict.
         type: dict
         suboptions:
@@ -51,17 +50,17 @@
                     - openshiftProjectName
 
     state:
-        description:
-        - Determines if the environment should be created, updated, or deleted. When set to C(present), the environment will be
-        created, if it does not already exist. If set to C(absent), an existing environment will be deleted. If set to
-        C(present), an existing environment will be updated, if its attributes differ from those specified using
-        I(definition).
+        description: |
+            Determines if the environment should be created, updated, or deleted. When set to C(present), the environment will be
+            created, if it does not already exist. If set to C(absent), an existing environment will be deleted. If set to
+            C(present), an existing environment will be updated, if its attributes differ from those specified using
+            I(definition).
         type: str
         default: present
         choices: [ absent, present ]
 
 extends_documentation_fragment:
-  - lagoon.api.auth_options
+    - lagoon.api.auth_options
 
 author:
     - Yusuf Hasan Miyan (@yusufhm)

api/plugins/modules/environment_update.py

@@ -5,7 +5,7 @@
 module: environment_update
 short_description: Update a project environment's values
 description:
-    - Updates a project environment's values.
+  - Updates a project environment's values.
 options:
   environment:
     description:
@@ -21,7 +21,7 @@
     description:
       - The environment values.
     type: dict
-    default: None
+    default: {}
 '''
 
 EXAMPLES = r'''

api/plugins/modules/metadata.py

@@ -25,9 +25,9 @@
     choices: [ absent, present ]
   data:
     description:
-      - The metadata values.
-    type: dict & list of dicts
-    default: None
+      - The metadata values - can be a dict or a list of dicts.
+    type: list
+    default: []
 '''
 
 EXAMPLES = r'''
@@ -38,7 +38,7 @@
       solr-version: 6
     project_id: 7
     project_name: project-pheonix
-    
+
 - name: Add project metadata (list of dicts)
   lagoon.api.metadata:
     state: present

api/plugins/modules/mutation.py

@@ -3,6 +3,7 @@
 
 DOCUMENTATION = r'''
 module: mutation
+description: Run a mutation against the Lagoon GraphQL API.
 short_description: Run a mutation against the Lagoon GraphQL API.
 options:
   mutation:

api/plugins/modules/project.py

@@ -3,6 +3,7 @@
 
 DOCUMENTATION = r'''
 module: project
+description: Manage a project
 short_description: Manage a project
 options:
   name:
@@ -12,9 +13,10 @@
     type: str
   git_url:
     description:
-      - Git URL, needs to be SSH Git URL in one of these two formats
-      -   - git@172.17.0.1/project1.git
-      -   - ssh://git@172.17.0.1:2222/project1.git.
+      - |
+        Git URL, needs to be SSH Git URL in one of these two formats
+          - git@172.17.0.1/project1.git
+          - ssh://git@172.17.0.1:2222/project1.git.
     required: true
     type: str
   subfolder:
@@ -23,32 +25,34 @@
       - Useful if you have multiple Lagoon projects per Git Repository.
     type: str
   branches:
-    description:
-      - Which branches should be deployed, can be one of:
-      -   - true - all branches are deployed
-      -   - false - no branches are deployed
-      -   - REGEX - regex of all branches that should be deployed, example: ^(main|staging)$
+    description: |
+      Which branches should be deployed, can be one of:
+        - true - all branches are deployed
+        - false - no branches are deployed
+        - REGEX - regex of all branches that should be deployed, example: ^(main|staging)$
     type: str
   pullrequests:
     description:
-      - Which Pull Requests should be deployed, can be one of:
-      -   - true - all pull requests are deployed
-      -   - false - no pull requests are deployed
-      -   - REGEX - regex of all Pull Request titles that should be deployed, example: [BUILD]
+      - |
+        Which Pull Requests should be deployed, can be one of:
+          - true - all pull requests are deployed
+          - false - no pull requests are deployed
+          - REGEX - regex of all Pull Request titles that should be deployed, example: [BUILD]
     type: str
   production_environment:
-    description:
-      - Which environment(the name) should be marked as the production environment.
-      - Important: If you change this, you need to deploy both environments
-      - (the current and previous one) that are affected in order for the
-      - change to propagate correctly.
+    description: |
+      Which environment(the name) should be marked as the production environment.
+        - Important: If you change this, you need to deploy both environments
+        - (the current and previous one) that are affected in order for the
+        - change to propagate correctly.
     type: str
   standby_production_environment:
-    description:
-      - Which environment(the name) should be marked as the production
-      - standby environment.
-      - Important: This is used to determine which environment should be marked
-      - as the standby production environment
+    description: |
+      Which environment(the name) should be marked as the production standby
+      environment.
+
+      Important: This is used to determine which environment should be marked
+      as the standby production environment.
     type: str
   auto_idle:
     description:

api/plugins/modules/project_group.py

@@ -3,6 +3,7 @@
 
 DOCUMENTATION = r'''
 module: project_group
+description: Manage the groups for a project
 short_description: Manage the groups for a project
 options:
   project:

api/plugins/modules/project_update.py

@@ -16,7 +16,7 @@
     description:
       - The project values.
     type: dict
-    default: None
+    default: {}
 '''
 
 EXAMPLES = r'''