add online docs to collection (#87)

* add online docs to collection

* prevent archlinux CI errors

.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

.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

CONTRIBUTING.md

@@ -193,14 +193,12 @@ verifier:
   name: ansible
 ```
 
-<!--
-# Collection Docs
+## Collection Docs
 
 In addition to the `README.md`s, we use `antsibull-docs` to generate sphinx documentation for both modules and roles (from the `meta/argument_specs.yml` file).
 See [here](https://docs.ansible.com/ansible/latest/dev_guide/developing_collections_documenting.html) for more information about the build process.
 
 The CI also builds the docs to ensure they don't break silently.
--->
 
 ## Misc Lifecycle Maintainer Information
 

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
 

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

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 (<namespace>.<name>) to an URL here.
+# You can replace either of <namespace> or <name> 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}"
+}

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

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

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

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_*

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:

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.

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.

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

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

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]