diff --git a/.docker/Dockerfile.docs b/.docker/Dockerfile.docs new file mode 100644 index 0000000..cf73333 --- /dev/null +++ b/.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" ] diff --git a/.gitignore b/.gitignore index 8fe0be3..86a46e7 100644 --- a/.gitignore +++ b/.gitignore @@ -4,3 +4,5 @@ api/tests/output .docker/mock-server/node_modules .docker/mock-server/package-lock.json + +built-docs diff --git a/Dockerfile b/Dockerfile deleted file mode 100644 index 5efbd9d..0000000 --- a/Dockerfile +++ /dev/null @@ -1,39 +0,0 @@ -FROM alpine AS builder - -ENV PYENV_ROOT=/opt/.pyenv - -ENV PATH="$PYENV_ROOT/bin:$PATH" -ENV PATH="$PYENV_ROOT/versions/3.11.0/bin:$PATH" -ENV PATH="$PYENV_ROOT/versions/3.10.8/bin:$PATH" -ENV PATH="$PYENV_ROOT/versions/3.9.15/bin:$PATH" -ENV PATH="$PYENV_ROOT/versions/3.8.15/bin:$PATH" - -RUN apk add --no-cache bash git \ - && git clone https://github.com/pyenv/pyenv.git $PYENV_ROOT \ - && apk add --no-cache \ - build-base libffi-dev openssl-dev bzip2-dev \ - zlib-dev xz-dev readline-dev sqlite-dev tk-dev \ - && pyenv install 3.8.15 \ - && pyenv install 3.9.15 \ - && pyenv install 3.10.8 \ - && pyenv install 3.11.0 \ - && python3.8 -m pip install ansible pytest pytest-forked \ - && python3.9 -m pip install ansible pytest pytest-forked \ - && python3.10 -m pip install ansible pytest pytest-forked \ - && python3.11 -m pip install ansible pytest pytest-forked - -FROM alpine - -ENV PYENV_ROOT=/opt/.pyenv - -ENV PATH="$PYENV_ROOT/bin:$PATH" -ENV PATH="$PYENV_ROOT/versions/3.11.0/bin:$PATH" -ENV PATH="$PYENV_ROOT/versions/3.10.8/bin:$PATH" -ENV PATH="$PYENV_ROOT/versions/3.9.15/bin:$PATH" -ENV PATH="$PYENV_ROOT/versions/3.8.15/bin:$PATH" - -COPY --from=builder $PYENV_ROOT $PYENV_ROOT - -RUN apk add --no-cache libffi - -ENTRYPOINT [ "ansible-test" ] diff --git a/README.md b/README.md index 70f78aa..4a17e3e 100644 --- a/README.md +++ b/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). diff --git a/api/galaxy.yml b/api/galaxy.yml index 4d8bf96..d491533 100644 --- a/api/galaxy.yml +++ b/api/galaxy.yml @@ -4,14 +4,15 @@ version: 1.3.0 readme: README.md authors: - - Yusuf Hasan Miyan - - Steve Worley + - Yusuf Hasan Miyan + - Steve Worley 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' diff --git a/api/plugins/inventory/lagoon.py b/api/plugins/inventory/lagoon.py index 8898213..cddacde 100644 --- a/api/plugins/inventory/lagoon.py +++ b/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 diff --git a/api/plugins/modules/deploy_target_config.py b/api/plugins/modules/deploy_target_config.py index 30427d7..296fd7f 100644 --- a/api/plugins/modules/deploy_target_config.py +++ b/api/plugins/modules/deploy_target_config.py @@ -2,7 +2,6 @@ # -*- coding: utf-8 -*- DOCUMENTATION = r''' ---- module: deploy_target_config short_description: Manage deploy target configs for a project. @@ -10,45 +9,46 @@ 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''' diff --git a/api/plugins/modules/environment.py b/api/plugins/modules/environment.py index 0cbf561..fb24977 100644 --- a/api/plugins/modules/environment.py +++ b/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) diff --git a/api/plugins/modules/environment_update.py b/api/plugins/modules/environment_update.py index 3b0555a..f3b09ab 100644 --- a/api/plugins/modules/environment_update.py +++ b/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''' diff --git a/api/plugins/modules/metadata.py b/api/plugins/modules/metadata.py index ccea5c3..b23c839 100644 --- a/api/plugins/modules/metadata.py +++ b/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 diff --git a/api/plugins/modules/mutation.py b/api/plugins/modules/mutation.py index 66a9fde..51c6ddb 100644 --- a/api/plugins/modules/mutation.py +++ b/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: diff --git a/api/plugins/modules/project.py b/api/plugins/modules/project.py index 2da16a7..bcb9f7d 100644 --- a/api/plugins/modules/project.py +++ b/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: diff --git a/api/plugins/modules/project_group.py b/api/plugins/modules/project_group.py index 5fc482c..86dae9c 100644 --- a/api/plugins/modules/project_group.py +++ b/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: diff --git a/api/plugins/modules/project_update.py b/api/plugins/modules/project_update.py index 5952261..5a648b5 100644 --- a/api/plugins/modules/project_update.py +++ b/api/plugins/modules/project_update.py @@ -16,7 +16,7 @@ description: - The project values. type: dict - default: None + default: {} ''' EXAMPLES = r''' diff --git a/api/plugins/modules/query.py b/api/plugins/modules/query.py index 9a7731e..d73826c 100644 --- a/api/plugins/modules/query.py +++ b/api/plugins/modules/query.py @@ -3,6 +3,7 @@ DOCUMENTATION = r''' module: query +description: Run a query against the Lagoon API. short_description: Run a query against the Lagoon API. options: query: diff --git a/api/plugins/modules/task.py b/api/plugins/modules/task.py index 3dc2f75..f5fa4f5 100644 --- a/api/plugins/modules/task.py +++ b/api/plugins/modules/task.py @@ -3,6 +3,7 @@ DOCUMENTATION = r''' module: task +description: Invoke a task on an environment. short_description: Invoke a task on an environment. options: environment: diff --git a/api/plugins/modules/token.py b/api/plugins/modules/token.py index 44fb87f..cd8fc48 100644 --- a/api/plugins/modules/token.py +++ b/api/plugins/modules/token.py @@ -3,6 +3,7 @@ DOCUMENTATION = r''' module: token +description: Fetches a Lagoon token using ssh short_description: Fetches a Lagoon token using ssh options: grant: diff --git a/api/plugins/modules/user_group.py b/api/plugins/modules/user_group.py index 1458ede..911652a 100644 --- a/api/plugins/modules/user_group.py +++ b/api/plugins/modules/user_group.py @@ -3,6 +3,7 @@ DOCUMENTATION = r''' module: user_group +description: Manage the groups for a user short_description: Manage the groups for a user options: email: diff --git a/api/plugins/modules/variables.py b/api/plugins/modules/variables.py index 6fde738..fcefe79 100644 --- a/api/plugins/modules/variables.py +++ b/api/plugins/modules/variables.py @@ -3,6 +3,7 @@ DOCUMENTATION = r''' module: variables +description: Get variables for a project or environment. short_description: Get variables for a project or environment. options: type: diff --git a/api/plugins/modules/whoami.py b/api/plugins/modules/whoami.py index 66a8e00..6c9c1ed 100644 --- a/api/plugins/modules/whoami.py +++ b/api/plugins/modules/whoami.py @@ -3,6 +3,7 @@ DOCUMENTATION = r''' module: whoami +description: Get information about the current user. short_description: Get information about the current user. ''' diff --git a/docker-compose.yml b/docker-compose.yml index bfbacef..f7a4334 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -12,3 +12,21 @@ services: command: ["npm", "start"] ports: - 4000 + + lint-docs: + build: + context: . + dockerfile: .docker/Dockerfile.docs + args: + - OPERATION=lint + volumes: + - ./api:/collections/ansible_collections/lagoon/api + working_dir: /collections/ansible_collections/lagoon/api + command: ["antsibull-docs", "lint-collection-docs", "--plugin-docs", "."] + + docs: + build: + context: . + dockerfile: .docker/Dockerfile.docs + ports: + - 9180:8000