diff --git a/.circleci/config.yml b/.circleci/config.yml index 9f14f65..483311a 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -1,7 +1,7 @@ version: 2.1 orbs: - collection-testing: maxhoesel-ansible/ansible-collection-testing@0.2.1 + collection-testing: maxhoesel-ansible/ansible-collection-testing@0.3.5 jobs: modules-sanity: @@ -21,14 +21,26 @@ jobs: - run: command: tests/test-modules-integration +filters: &tagged + tags: + # Official Semver Regex. Yes, it's LOOOONG + only: /^v(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/ + branches: + ignore: /.*/ + workflows: ci: jobs: - collection-testing/pre-commit-lint - #- collection-testing/antsibull-docs: - # collection-name: maxhoesel.caddy + - collection-testing/antsibull-docs - collection-testing/tox-role-scenarios: - parallelism: 15 + parallelism: 8 resource-class: large + - collection-testing/publish-github: + context: collection-publishing + filters: *tagged + - collection-testing/publish-galaxy: + context: collection-publishing + filters: *tagged - modules-sanity - modules-integration diff --git a/.readthedocs.yml b/.readthedocs.yml new file mode 100644 index 0000000..67de6dc --- /dev/null +++ b/.readthedocs.yml @@ -0,0 +1,29 @@ +version: 2 + +python: + install: + - requirements: docs/requirements.txt + +build: + os: "ubuntu-20.04" + tools: + python: "3.10" + apt_packages: + - rsync + jobs: + pre_build: + - > + . /home/docs/checkouts/readthedocs.org/user_builds/ansible-collection-caddy/envs/latest/bin/activate + && ansible-galaxy collection build --force + && ansible-galaxy collection install *.tar.gz --force + && cd docs + && mkdir temp-rst + && antsibull-docs --config-file antsibull-docs.cfg collection --use-current --dest-dir temp-rst maxhoesel.caddy + - cd docs && rsync -cprv --delete-after temp-rst/collections/ rst/collections/ + +sphinx: + fail_on_warning: true + +formats: + - pdf + - epub diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 837d098..3ec0c22 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -193,14 +193,12 @@ verifier: name: ansible ``` - ## Misc Lifecycle Maintainer Information diff --git a/README.md b/README.md index 98c4f56..91f14d6 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,14 @@ An Ansible collection containing roles/modules to install, configure and interac ## Components +--- +**📘 Documentation** + +- For role documentation, see their `README.md`s or the online docs [here](https://ansible-collection-caddy.readthedocs.io) +- For modules documentation, see the online docs [here](https://ansible-collection-caddy.readthedocs.io) + +--- + ### Roles | Role | Description | @@ -18,9 +26,9 @@ An Ansible collection containing roles/modules to install, configure and interac | Module | Description | |---------|-------------| -| `caddy_load` | Load a new config into Caddy -| `caddy_config_info` | Retrieve Caddys current configuration for a given path -| `caddy_config` | Create or update Caddys configuration for a given path +| [`caddy_load`](https://ansible-collection-caddy.readthedocs.io/en/latest/collections/maxhoesel/caddy/caddy_load_module.html) | Load a new config into Caddy +| [`caddy_config_info`](https://ansible-collection-caddy.readthedocs.io/en/latest/collections/maxhoesel/caddy/caddy_config_info_module.html) | Retrieve Caddys current configuration for a given path +| [`caddy_config`](https://ansible-collection-caddy.readthedocs.io/en/latest/collections/maxhoesel/caddy/caddy_config_module.html) | Create or update Caddys configuration for a given path ## Installation diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..2def98f --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,7 @@ +# Copyright (c) Ansible Project +# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt) +# SPDX-License-Identifier: GPL-3.0-or-later + +/temp-rst +/build +/rst/collections diff --git a/docs/antsibull-docs.cfg b/docs/antsibull-docs.cfg new file mode 100644 index 0000000..9714411 --- /dev/null +++ b/docs/antsibull-docs.cfg @@ -0,0 +1,22 @@ +# Copyright (c) Ansible Project +# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt) +# SPDX-License-Identifier: GPL-3.0-or-later + +breadcrumbs = true +indexes = true +use_html_blobs = false + +# You can specify ways to convert a collection name (.) to an URL here. +# You can replace either of or by "*" to match all values in that place, +# or use "*" for the collection name to match all collections. In the URL, you can use +# {namespace} and {name} for the two components of the collection name. If you want to use +# "{" or "}" in the URL, write "{{" or "}}" instead. Basically these are Python format +# strings (https://docs.python.org/3.8/library/string.html#formatstrings). +collection_url = { + * = "https://galaxy.ansible.com/{namespace}/{name}" +} + +# The same wildcard rules and formatting rules as for collection_url apply. +collection_install = { + * = "ansible-galaxy collection install {namespace}.{name}" +} diff --git a/docs/build.sh b/docs/build.sh new file mode 100755 index 0000000..4c6ea41 --- /dev/null +++ b/docs/build.sh @@ -0,0 +1,23 @@ +#!/usr/bin/env bash +# Copyright (c) Ansible Project +# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt) +# SPDX-License-Identifier: GPL-3.0-or-later + +set -e + +# Create collection documentation into temporary directory +rm -rf temp-rst +mkdir -p temp-rst +chmod og-w temp-rst # antsibull-docs wants that directory only readable by itself +antsibull-docs \ + --config-file antsibull-docs.cfg \ + collection \ + --use-current \ + --dest-dir temp-rst \ + maxhoesel.caddy + +# Copy collection documentation into source directory +rsync -cprv --delete-after temp-rst/collections/ rst/collections/ + +# Build Sphinx site +cd rst && sphinx-build -M html ./ ../build -c . -W --keep-going diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..11772a3 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,10 @@ +# Copyright (c) Ansible Project +# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt) +# SPDX-License-Identifier: GPL-3.0-or-later + +ansible-core>=2.13,<2.15 +antsibull-docs >= 1.0.0, < 2.0.0 +ansible-pygments +sphinx +sphinx-ansible-theme >= 0.9.0 +pyyaml diff --git a/docs/rst/conf.py b/docs/rst/conf.py new file mode 100644 index 0000000..8fd0438 --- /dev/null +++ b/docs/rst/conf.py @@ -0,0 +1,52 @@ +# Copyright (c) Ansible Project +# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt) +# SPDX-License-Identifier: GPL-3.0-or-later + +# This file only contains a selection of the most common options. For a full list see the +# documentation: +# http://www.sphinx-doc.org/en/master/config + +import yaml + +with open("../../galaxy.yml", encoding="utf-8") as f: + galaxy = yaml.safe_load(f) +version = galaxy["version"] +release = version + +project = 'maxhoesel.caddy' +# pylint: disable=redefined-builtin +copyright = 'Max Hösel and Contributor' + +title = 'maxhoesel.caddy Collection Documentation' +html_short_title = 'maxhoesel.caddy Docs' + +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'sphinx_antsibull_ext'] + +pygments_style = 'ansible' + +highlight_language = 'YAML+Jinja' + +html_theme = 'sphinx_ansible_theme' +html_show_sphinx = False + +display_version = False + +html_use_smartypants = True +html_use_modindex = False +html_use_index = False +html_copy_source = False + +# See https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#confval-intersphinx_mapping for the syntax +intersphinx_mapping = { + 'python': ('https://docs.python.org/2/', (None, '../python2.inv')), + 'python3': ('https://docs.python.org/3/', (None, '../python3.inv')), + 'jinja2': ('http://jinja.palletsprojects.com/', (None, '../jinja2.inv')), + 'ansible_devel': ('https://docs.ansible.com/ansible/devel/', (None, '../ansible_devel.inv')), + # If you want references to resolve to a released Ansible version (say, `5`), + # uncomment and replace X by this version: + # 'ansibleX': ('https://docs.ansible.com/ansible/X/', (None, '../ansibleX.inv')), +} + +default_role = 'any' + +nitpicky = True diff --git a/docs/rst/index.rst b/docs/rst/index.rst new file mode 100644 index 0000000..33e0580 --- /dev/null +++ b/docs/rst/index.rst @@ -0,0 +1,14 @@ + +.. _docsite_root_index: + +Welcome to the maxhoesel.caddy Ansible Collection Docs! +========================================================= + +See the below indices for a list of all the modules and roles included in this collection. + +.. toctree:: + :maxdepth: 1 + :caption: Components: + :glob: + + collections/index_* diff --git a/plugins/modules/caddy_config.py b/plugins/modules/caddy_config.py index 9e70960..190314d 100644 --- a/plugins/modules/caddy_config.py +++ b/plugins/modules/caddy_config.py @@ -29,7 +29,7 @@ create_path: description: > Whether to create the path pointing to the configuration if it doesn't exist yet. - For example, if I(path=apps/http/servers/myservice) C(apps/http/servers) does not exist yet, the required path entries will be created. + For example, if I(path=apps/http/servers/myservice) and C(apps/http/servers) does not exist yet, the required path entries will be created. Note that any digit path segments are treated as array indices. type: bool default: yes @@ -53,8 +53,8 @@ aliases: - name description: > - Configuration path to which the configuration content will be pushed. Note that C(config/) is automatically - appended. Example: "apps/http/servers/myservice" + Configuration path to which the configuration content will be pushed. Note that the path if is automatically + prefixed with C(config/). Example: C(apps/http/servers/myservice) type: path required: yes state: diff --git a/plugins/modules/caddy_load.py b/plugins/modules/caddy_load.py index fcfa442..b1466cc 100644 --- a/plugins/modules/caddy_load.py +++ b/plugins/modules/caddy_load.py @@ -13,7 +13,7 @@ short_description: Load a new configuration into Caddy version_added: '0.1.0' description: > - This module pushes a caddy configuration to the server via the /load API endpoint. + This module pushes a caddy configuration to the server via the C(/load) API endpoint. If no change between the currently running and future configuration is found, no changes will be made. notes: - Check mode is supported. diff --git a/roles/caddy_server/meta/argument_specs.yml b/roles/caddy_server/meta/argument_specs.yml index c08a0bf..35b030b 100644 --- a/roles/caddy_server/meta/argument_specs.yml +++ b/roles/caddy_server/meta/argument_specs.yml @@ -1,6 +1,22 @@ argument_specs: main: - short_description: Main entrypoint + short_description: Install and initialize a Caddy server + description: + - | + This role installs the stable version of Caddy from the official L(repositories,https://caddyserver.com/docs/install) and performs basic configuration. + The role will configure the server so that it can be managed with the modules in this collection. + Alternatively, you can also configure caddy with a Caddyfile by passing it to this role. + - | + The following distributions are currently supported: + + - Ubuntu 18.04 LTS or newer + - Debian 10 or newer + - A CentOS 8-compatible distribution like RockyLinux or AlmaLinux. RockyLinux is used for testing + - ArchLinux (tested against the latest package versions) + - | + Supported architectures: Anything supported by upstream caddy should work + - | + This role requires root access. Make sure to run this role with C(become: yes) or equivalent options: caddy_apply_config: description: Whether to apply the given caddy configuration. Set to false if you only want to install Caddy. diff --git a/roles/caddy_server/molecule/caddyfile/prepare.yml b/roles/caddy_server/molecule/caddyfile/prepare.yml index 50d9259..1400ec6 100644 --- a/roles/caddy_server/molecule/caddyfile/prepare.yml +++ b/roles/caddy_server/molecule/caddyfile/prepare.yml @@ -6,6 +6,8 @@ - hosts: archlinux tasks: + - name: Initialize keyring # noqa no-changed-when + shell: pacman-key --init && pacman -Sy archlinux-keyring --noconfirm - name: Upgrade system community.general.pacman: update_cache: yes diff --git a/roles/caddy_server/molecule/default/prepare.yml b/roles/caddy_server/molecule/default/prepare.yml index 50d9259..1400ec6 100644 --- a/roles/caddy_server/molecule/default/prepare.yml +++ b/roles/caddy_server/molecule/default/prepare.yml @@ -6,6 +6,8 @@ - hosts: archlinux tasks: + - name: Initialize keyring # noqa no-changed-when + shell: pacman-key --init && pacman -Sy archlinux-keyring --noconfirm - name: Upgrade system community.general.pacman: update_cache: yes diff --git a/tests/test-roles b/tests/test-roles index 52d1fcc..aaa1ed1 100755 --- a/tests/test-roles +++ b/tests/test-roles @@ -3,9 +3,6 @@ set -eu set -o pipefail -# Hostname to use for the ca container in molecule scenarios -export STEP_MOLECULE_CA_HOSTNAME=step-ca-molecule.localdomain - SCRIPT_DIRECTORY=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd ) USAGE=$(cat << EOF Usage: test-roles [filter] [--help, -h]