docs: Install with galaxy and use docsmith

Signed-off-by: Julien Riou <julien@riou.xyz>

.gitignore

@@ -0,0 +1 @@
+venv

README.md

@@ -4,10 +4,18 @@ Ansible role to manage a [Forgejo](https://forgejo.org/) instance.
 
 ## Installation
 
-Clone the repository in your local Ansible roles directory:
+Use Ansible Galaxy to install the role locally:
 
 ```
-git clone https://git.riou.xyz/jriou/ansible-role-forgejo.git ~/.ansible/roles/forgejo
+ansible-galaxy role install git+https://git.riou.xyz/jriou/jriou.forgejo.git
+```
+
+Or use a requirements.yml file:
+
+```yaml
+roles:
+  - src: git+https://git.riou.xyz/jriou/jriou.forgejo.git
+    type: git
 ```
 
 See [Storing and finding
@@ -23,8 +31,267 @@ Then define at least `forgejo_db_password` with a strong and secure password,
 encrypted using
 [ansible-vault](https://docs.ansible.com/ansible/latest/cli/ansible-vault.html).
 
-See list of [default variables](defaults/main.yml).
 
+## Table of Content
+
+<!-- ANSIBLE DOCSMITH TOC START -->
+* [Role variables](#variables)
+  * [`forgejo_server`](#variable-forgejo_server)
+  * [`forgejo_version`](#variable-forgejo_version)
+  * [`forgejo_home_dir`](#variable-forgejo_home_dir)
+  * [`forgejo_config_dir`](#variable-forgejo_config_dir)
+  * [`forgejo_web_port`](#variable-forgejo_web_port)
+  * [`forgejo_ssh_port`](#variable-forgejo_ssh_port)
+  * [`forgejo_db_username`](#variable-forgejo_db_username)
+  * [`forgejo_db_password`](#variable-forgejo_db_password)
+  * [`forgejo_db_database`](#variable-forgejo_db_database)
+  * [`forgejo_mailer`](#variable-forgejo_mailer)
+  * [`forgejo_service`](#variable-forgejo_service)
+  * [`forgejo_manage_iptables`](#variable-forgejo_manage_iptables)
+  * [`forgejo_allowed_sources`](#variable-forgejo_allowed_sources)
+  * [`forgejo_runners_version`](#variable-forgejo_runners_version)
+  * [`forgejo_runners_config_dir`](#variable-forgejo_runners_config_dir)
+  * [`forgejo_runners_instance`](#variable-forgejo_runners_instance)
+  * [`forgejo_runners`](#variable-forgejo_runners)
+<!-- ANSIBLE DOCSMITH TOC END -->
+<!-- ANSIBLE DOCSMITH MAIN START -->
+
+## Role variables<a id="variables"></a>
+
+The following variables can be configured for this role:
+
+| Variable | Type | Required | Default | Description (abstract) |
+|----------|------|----------|---------|------------------------|
+| `forgejo_server` | `bool` | No | `true` | Enable the server mode |
+| `forgejo_version` | `int` | No | `13` | Version of the Forgejo binaries |
+| `forgejo_home_dir` | `path` | No | `"/var/lib/forgejo"` | Path to the home directory |
+| `forgejo_config_dir` | `path` | No | `"/etc/forgejo"` | Path to the configuration directory |
+| `forgejo_web_port` | `int` | No | `3000` | Port to listen for the web UI |
+| `forgejo_ssh_port` | `int` | No | `222` | Port to listen for SSH |
+| `forgejo_db_username` | `str` | No | `"forgejo"` | Name of the user in the database |
+| `forgejo_db_password` | `str` | Yes | N/A | Password of the user in the database |
+| `forgejo_db_database` | `str` | No | `"forgejo"` | Name of the database |
+| `forgejo_mailer` | `dict` | No | N/A | Configure the mailer to send e-mail notifications<br><br>Define a `enabled` key with a boolean to enable the mailer<br><br>Define a `from` key with the source e-mail address<br><br>See [Email setup](https://forgejo.org/docs/latest/admin/setup/email/) |
+| `forgejo_service` | `dict` | No | N/A | Configure service settings<br><br>See [Service](https://forgejo.org/docs/latest/admin/config-cheat-sheet/#service-service) |
+| `forgejo_manage_iptables` | `bool` | No | `false` | Configure iptables rules |
+| `forgejo_allowed_sources` | `list` | No | N/A | List of IP ranges to allow when `forgejo_manage_iptables` is enabled |
+| `forgejo_runners_version` | `str` | No | `"9.1.1"` | Version of the runners |
+| `forgejo_runners_config_dir` | `path` | No | `"/etc/forgejo-runners"` | Path to the configuration directory of the runners |
+| `forgejo_runners_instance` | `str` | No | N/A | URL of the Forgejo instance to register the runners |
+| `forgejo_runners` | `dict` | No | N/A | List of runners to configure<br><br>The key is the name of the repository on the instance<br><br>The value is the token |
+
+### `forgejo_server`<a id="variable-forgejo_server"></a>
+
+[*⇑ Back to ToC ⇑*](#toc)
+
+Enable the server mode
+
+- **Type**: `bool`
+- **Required**: No
+- **Default**: `true`
+
+
+
+### `forgejo_version`<a id="variable-forgejo_version"></a>
+
+[*⇑ Back to ToC ⇑*](#toc)
+
+Version of the Forgejo binaries
+
+- **Type**: `int`
+- **Required**: No
+- **Default**: `13`
+
+
+
+### `forgejo_home_dir`<a id="variable-forgejo_home_dir"></a>
+
+[*⇑ Back to ToC ⇑*](#toc)
+
+Path to the home directory
+
+- **Type**: `path`
+- **Required**: No
+- **Default**: `"/var/lib/forgejo"`
+
+
+
+### `forgejo_config_dir`<a id="variable-forgejo_config_dir"></a>
+
+[*⇑ Back to ToC ⇑*](#toc)
+
+Path to the configuration directory
+
+- **Type**: `path`
+- **Required**: No
+- **Default**: `"/etc/forgejo"`
+
+
+
+### `forgejo_web_port`<a id="variable-forgejo_web_port"></a>
+
+[*⇑ Back to ToC ⇑*](#toc)
+
+Port to listen for the web UI
+
+- **Type**: `int`
+- **Required**: No
+- **Default**: `3000`
+
+
+
+### `forgejo_ssh_port`<a id="variable-forgejo_ssh_port"></a>
+
+[*⇑ Back to ToC ⇑*](#toc)
+
+Port to listen for SSH
+
+- **Type**: `int`
+- **Required**: No
+- **Default**: `222`
+
+
+
+### `forgejo_db_username`<a id="variable-forgejo_db_username"></a>
+
+[*⇑ Back to ToC ⇑*](#toc)
+
+Name of the user in the database
+
+- **Type**: `str`
+- **Required**: No
+- **Default**: `"forgejo"`
+
+
+
+### `forgejo_db_password`<a id="variable-forgejo_db_password"></a>
+
+[*⇑ Back to ToC ⇑*](#toc)
+
+Password of the user in the database
+
+- **Type**: `str`
+- **Required**: Yes
+
+
+
+### `forgejo_db_database`<a id="variable-forgejo_db_database"></a>
+
+[*⇑ Back to ToC ⇑*](#toc)
+
+Name of the database
+
+- **Type**: `str`
+- **Required**: No
+- **Default**: `"forgejo"`
+
+
+
+### `forgejo_mailer`<a id="variable-forgejo_mailer"></a>
+
+[*⇑ Back to ToC ⇑*](#toc)
+
+Configure the mailer to send e-mail notifications
+
+Define a `enabled` key with a boolean to enable the mailer
+
+Define a `from` key with the source e-mail address
+
+See [Email setup](https://forgejo.org/docs/latest/admin/setup/email/)
+
+- **Type**: `dict`
+- **Required**: No
+
+
+
+### `forgejo_service`<a id="variable-forgejo_service"></a>
+
+[*⇑ Back to ToC ⇑*](#toc)
+
+Configure service settings
+
+See [Service](https://forgejo.org/docs/latest/admin/config-cheat-sheet/#service-service)
+
+- **Type**: `dict`
+- **Required**: No
+
+
+
+### `forgejo_manage_iptables`<a id="variable-forgejo_manage_iptables"></a>
+
+[*⇑ Back to ToC ⇑*](#toc)
+
+Configure iptables rules
+
+- **Type**: `bool`
+- **Required**: No
+- **Default**: `false`
+
+
+
+### `forgejo_allowed_sources`<a id="variable-forgejo_allowed_sources"></a>
+
+[*⇑ Back to ToC ⇑*](#toc)
+
+List of IP ranges to allow when `forgejo_manage_iptables` is enabled
+
+- **Type**: `list`
+- **Required**: No
+
+
+
+### `forgejo_runners_version`<a id="variable-forgejo_runners_version"></a>
+
+[*⇑ Back to ToC ⇑*](#toc)
+
+Version of the runners
+
+- **Type**: `str`
+- **Required**: No
+- **Default**: `"9.1.1"`
+
+
+
+### `forgejo_runners_config_dir`<a id="variable-forgejo_runners_config_dir"></a>
+
+[*⇑ Back to ToC ⇑*](#toc)
+
+Path to the configuration directory of the runners
+
+- **Type**: `path`
+- **Required**: No
+- **Default**: `"/etc/forgejo-runners"`
+
+
+
+### `forgejo_runners_instance`<a id="variable-forgejo_runners_instance"></a>
+
+[*⇑ Back to ToC ⇑*](#toc)
+
+URL of the Forgejo instance to register the runners
+
+- **Type**: `str`
+- **Required**: No
+
+
+
+### `forgejo_runners`<a id="variable-forgejo_runners"></a>
+
+[*⇑ Back to ToC ⇑*](#toc)
+
+List of runners to configure
+
+The key is the name of the repository on the instance
+
+The value is the token
+
+- **Type**: `dict`
+- **Required**: No
+
+
+
+
+<!-- ANSIBLE DOCSMITH MAIN END -->
 
 ## Usage
 
@@ -33,7 +300,7 @@ Example of a basic forgejo.yml playbook:
 ```yaml
 - hosts: forgejo
   roles:
-    - forgejo
+    - jriou.forgejo
 ```
 
 Then run the playbook:

defaults/main.yml

@@ -1,26 +1,120 @@
 ---
+
+# Enable the server mode
+#
+# - Type: bool
+# - Required: No
+# - Default: true
 forgejo_server: true
+
+# Version of the Forgejo binaries
+#
+# - Type: int
+# - Required: No
+# - Default: 13
 forgejo_version: 13
+
+# Path to the home directory
+#
+# - Type: path
+# - Required: No
+# - Default: /var/lib/forgejo
 forgejo_home_dir: /var/lib/forgejo
+
+# Path to the configuration directory
+#
+# - Type: path
+# - Required: No
+# - Default: /etc/forgejo
 forgejo_config_dir: /etc/forgejo
+
+# Port to listen for the web UI
+#
+# - Type: int
+# - Required: No
+# - Default: 3000
 forgejo_web_port: 3000
+
+# Port to listen for SSH
+#
+# - Type: int
+# - Required: No
+# - Default: 222
 forgejo_ssh_port: 222
+
+# Name of the user in the database
+#
+# - Type: str
+# - Required: No
+# - Default: forgejo
 forgejo_db_username: forgejo
+
+# Password of the user in the database
+#
+# - Type: str
+# - Required: Yes
 forgejo_db_password: CHANGEME
+
+# Name of the database
+#
+# - Type: str
+# - Required: No
+# - Default: forgejo
 forgejo_db_database: forgejo
-# forgejo_mailer:
+
-#   enabled: "true"
+# Configure the mailer to send e-mail notifications
-#   from: email@test.eu
+#
-# https://forgejo.org/docs/latest/admin/setup/email/
+# Define a `enabled` key with a boolean to enable the mailer
+#
+# Define a `from` key with the source e-mail address
+#
+# See
+#
+# - Type: dict
+# - Required: No
 forgejo_mailer: {}
-# forgejo_service:
+
-#   enable_notify_mail: "true"
+# Configure service settings
+#
+# See
+#
+# - Type: dict
+# - Required: No
 forgejo_service: {}
+
+# Configure iptables rules
+#
+# - Type: bool
+# - Required: No
+# - Default: false
 forgejo_manage_iptables: false
+
+# List of IP ranges to allow when `forgejo_manage_iptables` is enabled
+#
+# - Type: list
+# - Required: No
 forgejo_allowed_sources: []
+
+# Version of the runners
+#
+# - Type: str
+# - Required: No
+# - Default: 9.1.1
 forgejo_runners_version: 9.1.1
+
+# Path to the configuration directory of the runners
+#
+# - Type: path
+# - Required: No
+# - Default: /etc/forgejo-runners
 forgejo_runners_config_dir: /etc/forgejo-runners
-# forgejo_runners_instance:
+
-# forgejo_runners:
+# List of runners to configure
-#   repository: token
+#
+# The key is the name of the repository on the instance
+#
+# The value is the token
+#
+# - Type: dict
+# - Required: No
 forgejo_runners: {}

meta/argument_specs.yml

@@ -0,0 +1,106 @@
+---
+argument_specs:
+  main:
+    short_description: Install and configure a Forgejo instance
+    description:
+      - Install and configure a [Forgejo](https://forgejo.org/) instance.
+    author:
+      - jriou
+    options:
+      forgejo_server:
+        description:
+          - Enable the server mode
+        type: bool
+        default: true
+
+      forgejo_version:
+        description:
+          - Version of the Forgejo binaries
+        type: int
+        default: 13
+
+      forgejo_home_dir:
+        description:
+          - Path to the home directory
+        type: path
+        default: /var/lib/forgejo
+
+      forgejo_config_dir:
+        description:
+          - Path to the configuration directory
+        type: path
+        default: /etc/forgejo
+
+      forgejo_web_port:
+        description:
+          - Port to listen for the web UI
+        type: int
+        default: 3000
+
+      forgejo_ssh_port:
+        description:
+          - Port to listen for SSH
+        type: int
+        default: 222
+
+      forgejo_db_username:
+        description:
+          - Name of the user in the database
+        default: forgejo
+
+      forgejo_db_password:
+        description:
+          - Password of the user in the database
+        required: true
+
+      forgejo_db_database:
+        description:
+          - Name of the database
+        default: forgejo
+
+      forgejo_mailer:
+        description:
+          - Configure the mailer to send e-mail notifications
+          - Define a `enabled` key with a boolean to enable the mailer
+          - Define a `from` key with the source e-mail address
+          - See [Email setup](https://forgejo.org/docs/latest/admin/setup/email/)
+        type: dict
+
+      forgejo_service:
+        description:
+          - Configure service settings
+          - See [Service](https://forgejo.org/docs/latest/admin/config-cheat-sheet/#service-service)
+        type: dict
+
+      forgejo_manage_iptables:
+        description:
+          - Configure iptables rules
+        type: bool
+        default: false
+
+      forgejo_allowed_sources:
+        description:
+          - List of IP ranges to allow when `forgejo_manage_iptables` is enabled
+        type: list
+
+      forgejo_runners_version:
+        description:
+          - Version of the runners
+        default: 9.1.1
+
+      forgejo_runners_config_dir:
+        description:
+          - Path to the configuration directory of the runners
+        type: path
+        default: /etc/forgejo-runners
+
+      forgejo_runners_instance:
+        description:
+          - URL of the Forgejo instance to register the runners
+
+      forgejo_runners:
+        description:
+          - List of runners to configure
+          - The key is the name of the repository on the instance
+          - The value is the token
+        type: dict

tasks/deploy-server.yml

@@ -1,4 +1,8 @@
 ---
+- name: check database password
+  ansible.builtin.assert:
+    that: forgejo_db_password is defined
+
 - name: create directories
   ansible.builtin.file:
     state: directory