Skip to content

Commit 7e45814

Browse files
medantheliniummedanthelinium
committed
Remove legacy config options, add argument_specs, generate documentation automatically
1 parent 3366dee commit 7e45814

File tree

7 files changed

+292
-26
lines changed

7 files changed

+292
-26
lines changed

‎.aar-doc.yml

+99
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
---
2+
output_file: README.md
3+
output_mode: replace
4+
output_template: |
5+
<!-- BEGIN_ANSIBLE_DOCS -->
6+
# {{ role }}
7+
8+
{{ metadata.galaxy_info.description }}
9+
10+
## Supported Operating Systems
11+
12+
- Debian 12
13+
- Ubuntu 24.04, 22.04
14+
- FreeBSD [Proserver](https://infrastructure.punkt.de/de/produkte/proserver.html)
15+
16+
## Role Arguments
17+
18+
{% for entrypoint in argument_specs.keys() %}
19+
20+
{% if "description" in argument_specs[entrypoint] %}
21+
{%- if argument_specs[entrypoint].description is string -%}
22+
{{ argument_specs[entrypoint].description }}
23+
{% else %}
24+
{%- for line in argument_specs[entrypoint].description -%}
25+
{{ line }}
26+
27+
{% endfor -%}
28+
{% endif -%}
29+
{% endif -%}
30+
31+
{% if entrypoint_options[entrypoint] | length > 1 -%}
32+
33+
{% for path, options in entrypoint_options[entrypoint][1:] -%}
34+
#### Options for `{{ path | reject('eq', 'main') | join(".") }}`
35+
36+
|Option|Description|Type|Required|Default|
37+
|---|---|---|---|---|
38+
{%- for name, details in options.items() %}
39+
| `{{ name }}` | {{ details.display_description }} | {{ details.display_type }} | {{ details.display_required }} | {{ details.display_default }} |
40+
{%- endfor %}
41+
42+
{% endfor -%}
43+
44+
{% endif -%}
45+
46+
{% if entrypoint in entrypoint_choices -%}
47+
{% for path, choices in entrypoint_choices[entrypoint] -%}
48+
#### Choices for {{ path | join(" > ") }}
49+
50+
|Choice|
51+
|---|
52+
{%- for item in choices %}
53+
| {{ item }} |
54+
{%- endfor %}
55+
56+
{% endfor -%}
57+
{% endif -%}
58+
{% else -%}
59+
60+
This entrypoint has no options.
61+
62+
{% endfor -%}
63+
64+
## Dependencies
65+
66+
{%- if ("dependencies" in metadata) and (metadata.dependencies | length > 0) %}
67+
{%- for dependency in metadata.dependencies %}
68+
{%- if dependency.src %}
69+
- [{{ dependency.role }}]({{ dependency.src }})
70+
{%- else %}
71+
- {{ dependency.role }}
72+
{%- endif %}
73+
{%- if dependency.when %}
74+
- **Condition**: `{{ dependency.when }}`
75+
{%- endif %}
76+
{%- endfor %}
77+
{%- else %}
78+
None.
79+
{%- endif %}
80+
81+
## Installation
82+
Add this role to the requirements.yml of your playbook as follows:
83+
```yaml
84+
roles:
85+
- name: php
86+
src: https://github.com/punktDe/ansible-proserver-php
87+
```
88+
89+
Afterwards, install the role by running `ansible-galaxy install -r requirements.yml`
90+
91+
## Example Playbook
92+
93+
```yaml
94+
- hosts: all
95+
roles:
96+
- name: php
97+
```
98+
99+
<!-- END_ANSIBLE_DOCS -->

‎.github/workflows/generate_readme.yml

+49
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
---
2+
name: Generate README.md for the role
3+
4+
on:
5+
push:
6+
branches:
7+
- '**'
8+
tags-ignore:
9+
- '**'
10+
workflow_dispatch:
11+
12+
permissions:
13+
contents: write
14+
15+
jobs:
16+
readme:
17+
name: Generate README.md from argument specs
18+
runs-on: ubuntu-latest
19+
steps:
20+
- name: Checkout
21+
uses: actions/checkout@v3
22+
23+
- name: Install uv
24+
uses: astral-sh/setup-uv@v5
25+
26+
- name: Set up Python
27+
run: uv python install
28+
29+
- name: Install dependencies
30+
run: |
31+
uv -q venv --allow-existing --seed .venv
32+
. .venv/bin/activate
33+
uv -q pip install -r requirements.txt
34+
35+
- name: Run aar-doc
36+
run: |
37+
. .venv/bin/activate
38+
aar-doc --output-mode replace --config-file .aar-doc.yml . markdown
39+
40+
- name: Output diff
41+
run: git diff README.md
42+
43+
- name: Commit and push README
44+
run: |
45+
git config user.name github-actions
46+
git config user.email [email protected]
47+
git add README.md
48+
git diff-index --quiet HEAD || git commit -m "chore: Generate README.md"
49+
git push

‎defaults/main.yaml

-6
Original file line numberDiff line numberDiff line change
@@ -17,12 +17,6 @@ php:
1717
{%- endif -%}
1818
version: "{{ ansible_local.php.version }}"
1919
prefix: "{{ ansible_local.php.prefix }}"
20-
xdebug:
21-
# Xdebug is not installed in a real proServer environment.
22-
# This option is only useful in a development environment.
23-
# If enabled, Ansible will disable Xdebug and provide the command "xdebug",
24-
# which can be used to enable/disable Xdebug when desired.
25-
disable_by_default: no
2620
php.ini: {}
2721
fpm:
2822
service: "{{ ansible_local.php.fpm.service }}"

‎meta/argument_specs.yml

+140
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
---
2+
argument_specs:
3+
main:
4+
short_description: Main entry point for the PHP role
5+
description:
6+
- Default variables that begin with `ansible_local` are populated
7+
using the PHP fact script (files/php.fact.py).
8+
- This scripts detects many PHP-related variables automatically
9+
depending on the system (e.g. PHP version, PHP-FPM service name,
10+
configuration, directories).
11+
- The fact script is copied to the target machine at the beginning
12+
of the role execution, even in `check_mode`.
13+
- Apart from `php.version` (on a Debian-based system), you probably
14+
shouldn't change the variables starting with `ansible_local`,
15+
unless you know what you're doing.
16+
options:
17+
php:
18+
type: "dict"
19+
required: true
20+
options:
21+
repository:
22+
type: "dict"
23+
required: true
24+
description:
25+
- Configuration options for an optional 3rd party APT repository used to install
26+
alternative PHP versions (only applies for Debian-based systems)
27+
options:
28+
apt:
29+
type: "dict"
30+
required: true
31+
options:
32+
enabled:
33+
type: "bool"
34+
default: false
35+
description:
36+
- Whether the 3rd party APT repository should be installed and used
37+
key_url:
38+
type: "str"
39+
required: true
40+
description:
41+
- URL for the GPG key used to signed the APT repository
42+
repository:
43+
type: "str"
44+
required: true
45+
description:
46+
- URL for the APT repository
47+
version:
48+
type: str
49+
default: "{{ ansible_local.php.version }}"
50+
description:
51+
- PHP version to be installed (in case of Debian-based systems) and configured
52+
on the target machine.
53+
- On FreeBSD Proserver-based systems, PHP is already pre-installed. The PHP version
54+
depends on the system Blueprint and is extracted automatically from the output
55+
of `php -v`. Hence, setting this variable is not required.
56+
- On Debian-based systems, this variable defaults to the newest possible version that
57+
can be installed using the APT package manager. Provided you've enabled the 3rd party
58+
APT repository using `php.repository.apt.enabled`, you can set this variable to the
59+
desired version of PHP, as long as it's actually available in the repositories.
60+
This can be checked by using `apt search --names-only php`.
61+
prefix:
62+
type: dict
63+
default: "{{ ansible_local.php.prefix }}"
64+
description:
65+
- Directories for PHP configuration files (e.g. php.ini).
66+
- "Defaults to `config: \"/etc/php/{{ php.version }}/cli\"` on Linux
67+
and `config: \"/usr/local/etc\"` on FreeBSD."
68+
- Most of the time, you probably don't need to change this variable.
69+
php.ini:
70+
type: dict
71+
default: {}
72+
description:
73+
- Defines config options to be written into php.ini.
74+
- "The options are defined as key-value pairs in a YAML dictionary,
75+
e.g. `memory_limit: 2G` or `upload_max_filesize: 500M`"
76+
fpm:
77+
type: dict
78+
required: true
79+
description:
80+
- PHP-FPM configuration
81+
options:
82+
service:
83+
type: str
84+
default: "{{ ansible_local.php.fpm.service }}"
85+
description:
86+
- PHP-FPM service name
87+
prefix:
88+
type: str
89+
default: "{{ ansible_local.php.fpm.prefix }}"
90+
description:
91+
- Path to PHP-FPM configuration files.
92+
- Contains "config" and "pool_config" parameters,
93+
which default to `/usr/local/etc and /usr/local/etc/php-fpm.d` on
94+
FreeBSD, and `/etc/php/{{ php.version }}/fpm` and
95+
`/etc/php/{{ php.version }}/fpm/pool.d` on Linux respectively.
96+
pools:
97+
type: dict
98+
default:
99+
www:
100+
user: proserver
101+
group: proserver
102+
listen.owner: proserver
103+
listen.group: "{{ ansible_local.php.fpm.pools.www['listen.group'] }}"
104+
listen: "{{ ansible_local.php.fpm.pools.www.listen }}"
105+
description:
106+
- Defines PHP-FPM pools.
107+
- By default, only `www` pool is defined which runs
108+
under user `proserver:proserver`
109+
phpfpmtop:
110+
type: dict
111+
description:
112+
- Options for phpfpmtop, a performance monitor
113+
for PHP-FPM.
114+
options:
115+
release:
116+
type: dict
117+
options:
118+
url:
119+
type: str
120+
description:
121+
- URL to the phpfpmtop binary.
122+
checksum:
123+
type: str
124+
description:
125+
- SHA256 checksum of the phpfpmtop binary.
126+
install_extensions:
127+
type: dict
128+
default: {}
129+
description:
130+
- "Defines PHP extensions to be installed on the target machine
131+
in the `{'extension_name': true}` format,
132+
e.g. `{'pdo-mysql': true, 'mbstring': true}`."
133+
- Only applies to Debian-based targets.
134+
install_composer:
135+
type: bool
136+
default: false
137+
description:
138+
- Whether to install [Composer](https://getcomposer.org) on
139+
the target machine.
140+
- Only applies to Debian-based targets.

‎meta/main.yaml ‎meta/main.yml

+3-2
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,9 @@
11
---
22
galaxy_info:
33
author: "Punkt.de"
4-
license: ""
4+
license: "MIT"
55
description: "Ansible role for PHP"
6-
role_name: "proserver_php"
6+
role_name: "php"
77
namespace: "punktde"
88
min_ansible_version: "2.15"
9+
platforms: []

‎requirements.txt

+1
Original file line numberDiff line numberDiff line change
@@ -5,3 +5,4 @@ molecule<25.2.0
55
molecule-plugins
66
yamllint
77
requests
8+
aar-doc

‎tasks/xdebug.yaml

-18
This file was deleted.

0 commit comments

Comments
 (0)