From 22049cd1cae7b6e5f33b435fc9f4cd767720e597 Mon Sep 17 00:00:00 2001 From: Kevin Veen-Birkenbach Date: Wed, 9 Jul 2025 17:42:28 +0200 Subject: [PATCH] Optimized README's and meta/main.ymls for Sphinx Build --- roles/desk-torbrowser/README.md | 38 ++++------ roles/desk-torbrowser/meta/main.yml | 23 ++++++ roles/drv-intel/README.md | 18 ++--- roles/drv-intel/meta/main.yml | 25 +++++++ roles/utils-desk-office-tools/README.md | 47 +++++-------- roles/utils-desk-office-tools/meta/main.yml | 29 +++++++- .../test_ansible_roles_metadata.py | 70 +++++++++++++++++++ 7 files changed, 185 insertions(+), 65 deletions(-) create mode 100644 roles/desk-torbrowser/meta/main.yml create mode 100644 roles/drv-intel/meta/main.yml create mode 100644 tests/integration/test_ansible_roles_metadata.py diff --git a/roles/desk-torbrowser/README.md b/roles/desk-torbrowser/README.md index b3ad18e1..9bab34ab 100644 --- a/roles/desk-torbrowser/README.md +++ b/roles/desk-torbrowser/README.md @@ -1,31 +1,23 @@ -# PC-TorBrowser Role +# Torbrowser + +## Description + +This Ansible role installs and configures the Tor service and the Tor Browser Launcher, providing a privacy-focused web browsing environment on Pacman-based Linux distributions. ## Overview -This README document is for the `desk-torbrowser` role, a crucial component of the `cymais` repository. This role is specifically designed for the installation and setup of Tor Browser on personal computers. -## Role Tasks -The `main.yml` file under the `desk-torbrowser` role encompasses tasks for installing the Tor Browser: +The `desk-torbrowser` role uses the `community.general.pacman` module to: -1. **Install TorBrowser**: - - Utilizes the `community.general.pacman` module to install: - - `tor`: The core Tor service which facilitates anonymous communication. - - `torbrowser-launcher`: A package for securely and easily launching the Tor Browser. +1. Install **tor** (the core Tor network service) +2. Install **torbrowser-launcher** (the launcher for Tor Browser) -## Purpose and Usage -The `desk-torbrowser` role is tailored for users who value privacy and anonymity online. The Tor Browser is a specialized web browser that provides enhanced privacy features, making it an essential tool for secure browsing and accessing the deep web. +## Features -## Prerequisites -- **Ansible**: Must be installed on your system to run this role. -- **Arch Linux-based System**: As the role uses the `pacman` package manager, it's best suited for Arch Linux or similar distributions. +* Idempotent installation of Tor and Tor Browser Launcher +* Ensures the Tor service is available for anonymous network traffic +* Simplifies first-time setup of Tor Browser -## Running the Role -To use this role: -1. Clone the `cymais` repository. -2. Navigate to the `roles/desk-torbrowser` directory. -3. Run the role using Ansible, ensuring you have the necessary permissions for software installation. +## Further Resources -## Customization -While this role primarily focuses on installing Tor and the Tor Browser Launcher, you can customize it to include additional privacy-focused tools or configurations based on your needs. - -## Support and Contributions -For support, feedback, or contributions, such as enhancing the role with more privacy tools or improving the installation process, please open an issue or submit a pull request in the `cymais` repository. Contributions that enhance the privacy and security aspects of this role are highly encouraged. \ No newline at end of file +* [Tor Project documentation](https://www.torproject.org/) +* [CyMaIS GitHub repository](https://github.com/kevinveenbirkenbach/cymais) \ No newline at end of file diff --git a/roles/desk-torbrowser/meta/main.yml b/roles/desk-torbrowser/meta/main.yml new file mode 100644 index 00000000..4e90e06b --- /dev/null +++ b/roles/desk-torbrowser/meta/main.yml @@ -0,0 +1,23 @@ +galaxy_info: + author: "Kevin Veen-Birkenbach" + description: "Installs and configures the Tor service and Tor Browser Launcher for secure, anonymous web browsing on Pacman-based systems." + license: "CyMaIS NonCommercial License (CNCL)" + license_url: "https://s.veen.world/cncl" + company: | + Kevin Veen-Birkenbach + Consulting & Coaching Solutions + https://www.veen.world + galaxy_tags: + - tor + - privacy + - anonymity + - browser + repository: "https://github.com/kevinveenbirkenbach/cymais" + issue_tracker_url: "https://github.com/kevinveenbirkenbach/cymais/issues" + documentation: "https://github.com/kevinveenbirkenbach/cymais/tree/main/roles/desk-torbrowser" + min_ansible_version: "2.9" + platforms: + - name: Archlinux + versions: + - all +dependencies: [] diff --git a/roles/drv-intel/README.md b/roles/drv-intel/README.md index 3b4ae7f9..ad135535 100644 --- a/roles/drv-intel/README.md +++ b/roles/drv-intel/README.md @@ -1,22 +1,22 @@ -# Intel Drivers +# drv-intel Role ## Description -This Ansible role installs Intel media drivers on systems that use the Pacman package manager (e.g., Arch Linux and derivatives). It ensures the `intel-media-driver` package is present and up-to-date. +This Ansible role installs Intel media drivers on Pacman-based Linux distributions (e.g., Arch Linux), ensuring the `intel-media-driver` package is present and up-to-date. ## Overview -The `drv-intel` role leverages the `community.general.pacman` module to: +The `drv-intel` role uses the `community.general.pacman` module to: -1. Update the package cache. -2. Install (or upgrade) the `intel-media-driver` package. -3. Verify that the driver is correctly installed and ready for use in media pipelines. +1. Update the package cache +2. Install or upgrade the `intel-media-driver` package +3. Verify the driver installation for media pipelines ## Features -* Idempotent installation of Intel media drivers -* Automatic package cache update before installation -* Supports installation on any Pacman-based distribution +* Idempotent installation of Intel media drivers +* Automatic Pacman cache update +* Support for all Pacman-based distributions ## Further Resources diff --git a/roles/drv-intel/meta/main.yml b/roles/drv-intel/meta/main.yml new file mode 100644 index 00000000..10878ec8 --- /dev/null +++ b/roles/drv-intel/meta/main.yml @@ -0,0 +1,25 @@ +--- +galaxy_info: + author: "Kevin Veen-Birkenbach" + description: "Installs Intel media drivers on Pacman-based systems, ensuring the `intel-media-driver` package is present and up-to-date." + license: "CyMaIS NonCommercial License (CNCL)" + license_url: "https://s.veen.world/cncl" + company: | + Kevin Veen-Birkenbach + Consulting & Coaching Solutions + https://www.veen.world + galaxy_tags: + - intel + - media + - driver + - linux + - pacman + repository: "https://github.com/kevinveenbirkenbach/cymais" + issue_tracker_url: "https://github.com/kevinveenbirkenbach/cymais/issues" + documentation: "https://github.com/kevinveenbirkenbach/cymais/tree/main/roles/drv-intel" + min_ansible_version: "2.9" + platforms: + - name: Archlinux + versions: + - all +dependencies: [] diff --git a/roles/utils-desk-office-tools/README.md b/roles/utils-desk-office-tools/README.md index f95c1565..60a5e12d 100644 --- a/roles/utils-desk-office-tools/README.md +++ b/roles/utils-desk-office-tools/README.md @@ -1,38 +1,23 @@ -# Employee +# utils-desk-office-tools Role + +## Description + +This Ansible role installs a comprehensive suite of office productivity tools on Pacman-based Linux distributions, including a web browser, email client, e-book manager, and document editor. ## Overview -This README document is for the `utils-desk-office-tools` role, a component of the `cymais` repository. This role is designed to install a suite of office-related software on personal computers, providing a comprehensive set of tools for various office tasks. -## Role Tasks -The `main.yml` file within the `utils-desk-office-tools` role comprises tasks for installing a range of office software: +The `utils-desk-office-tools` role uses the `community.general.pacman` module to: -1. **Install Office Software**: - - The role utilizes the `community.general.pacman` module to install the following software packages: - - `chromium`: A free and open-source web browser. - - `thunderbird`: A free and open-source email client, news client, RSS, and chat client. - - `calibre`: An e-book management software. - - `retext`: A simple but powerful editor for Markdown and reStructuredText. +1. Install **Chromium** (web browser) +2. Install **Thunderbird** (email and RSS client) +3. Install **Calibre** (e-book management software) +4. Install **ReText** (Markdown and reStructuredText editor) -## Dependencies -This role depends on: -- **desk-libreoffice**: Ensures that the LibreOffice suite, a comprehensive office package, is installed. -- **desk-zoom**: Provides tools necessary for video conferencing, supplementing the office setup. +## Features -## Purpose and Usage -The `utils-desk-office-tools` role is ideal for users who require a full-fledged office setup on their personal computers. It encompasses tools for web browsing, email management, e-book organization, and document editing, catering to a wide range of office and productivity needs. +* Idempotent installation of all specified office packages +* Supports any Pacman-based distribution (e.g., Arch Linux) +* Easily extendable by adding or removing package names -## Prerequisites -- **Ansible**: Must be installed to use this role. -- **Arch Linux-based System**: As the role uses the `pacman` package manager, it's intended for systems based on Arch Linux or similar distributions. - -## Running the Role -To utilize this role: -1. Clone the `cymais` repository. -2. Navigate to the `roles/utils-desk-office-tools` directory. -3. Run the role using Ansible, ensuring you have the necessary permissions for software installation. - -## Customization -This role can be customized by adding or removing software packages in the `main.yml` file, depending on your specific office and productivity needs. - -## Support and Contributions -For support, feedback, or contributions, such as adding more office tools or enhancing the current setup, please open an issue or submit a pull request in the `cymais` repository. Contributions that improve the office and productivity environment are highly welcomed. \ No newline at end of file +## Further Resources +* [CyMaIS GitHub repository](https://github.com/kevinveenbirkenbach/cymais) diff --git a/roles/utils-desk-office-tools/meta/main.yml b/roles/utils-desk-office-tools/meta/main.yml index 34afff93..83353257 100644 --- a/roles/utils-desk-office-tools/meta/main.yml +++ b/roles/utils-desk-office-tools/meta/main.yml @@ -1,3 +1,28 @@ +--- +galaxy_info: + author: "Kevin Veen-Birkenbach" + description: "Installs a suite of office productivity tools—web browser, email client, e-book manager, and reStructuredText/Markdown editor—on Pacman-based systems." + license: "CyMaIS NonCommercial License (CNCL)" + license_url: "https://s.veen.world/cncl" + company: | + Kevin Veen-Birkenbach + Consulting & Coaching Solutions + https://www.veen.world + galaxy_tags: + - office + - productivity + - browser + - email + - ebook + - editor + repository: "https://github.com/kevinveenbirkenbach/cymais" + issue_tracker_url: "https://github.com/kevinveenbirkenbach/cymais/issues" + documentation: "https://github.com/kevinveenbirkenbach/cymais/tree/main/roles/utils-desk-office-tools" + min_ansible_version: "2.9" + platforms: + - name: Archlinux + versions: + - all dependencies: -- desk-libreoffice -- utils-desk-browser \ No newline at end of file + - desk-libreoffice + - utils-desk-browser diff --git a/tests/integration/test_ansible_roles_metadata.py b/tests/integration/test_ansible_roles_metadata.py new file mode 100644 index 00000000..ca0b685f --- /dev/null +++ b/tests/integration/test_ansible_roles_metadata.py @@ -0,0 +1,70 @@ +import os +import yaml +import unittest + + +class TestAnsibleRolesMetadata(unittest.TestCase): + ROOT_DIR = os.path.abspath(os.path.join(os.path.dirname(__file__), '..', '..')) + ROLES_DIR = os.path.join(ROOT_DIR, 'roles') + + @classmethod + def setUpClass(cls): + if not os.path.isdir(cls.ROLES_DIR): + raise unittest.SkipTest(f"Roles directory not found at {cls.ROLES_DIR}") + cls.roles = [d for d in os.listdir(cls.ROLES_DIR) + if os.path.isdir(os.path.join(cls.ROLES_DIR, d))] + + def test_each_role_has_valid_meta(self): + """ + Ensure each Ansible role has a valid meta/main.yml + with the fields that Sphinx generators expect. + """ + for role in self.roles: + with self.subTest(role=role): + role_path = os.path.join(self.ROLES_DIR, role) + meta_file = os.path.join(role_path, 'meta', 'main.yml') + self.assertTrue( + os.path.exists(meta_file), + msg=f"Missing meta/main.yml in role '{role}'" + ) + + with open(meta_file, 'r', encoding='utf-8') as f: + raw = f.read() + meta_data = yaml.safe_load(raw) or {} + + # meta_data must be a dict + self.assertIsInstance( + meta_data, dict, + msg=f"Meta data for role '{role}' is not a dict" + ) + + # description inside galaxy_info + galaxy_info = meta_data.get('galaxy_info') or {} + self.assertIsInstance( + galaxy_info, dict, + msg=f"'galaxy_info' missing or not a dict in meta for role '{role}'" + ) + + self.assertIn( + 'description', galaxy_info, + msg=f"'description' missing in galaxy_info for role '{role}'" + ) + self.assertTrue( + galaxy_info['description'], + msg=f"'description' is empty in galaxy_info for role '{role}'" + ) + + # no empty keys or None values in galaxy_info + for key, value in galaxy_info.items(): + self.assertTrue( + key, + msg=f"Empty galaxy_info key in role '{role}'" + ) + self.assertIsNotNone( + value, + msg=f"None value for galaxy_info['{key}'] in role '{role}'" + ) + + +if __name__ == '__main__': + unittest.main()