kevinveenbirkenbach/computer-playbook
1
0
Fork 0
mirror of https://github.com/kevinveenbirkenbach/computer-playbook.git synced 2025-03-26 03:03:32 +01:00
Code Issues Packages Projects Releases Wiki Activity

Optimized sphinx and documentation

Browse Source
This commit is contained in:
Kevin Veen-Birkenbach 2025-03-15 18:33:59 +01:00
parent 12e0367c66
commit c1aa6823b0
No known key found for this signature in database
GPG Key ID: 44D8F11FD62F878E
19 changed files with 76 additions and 252 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

0
ARCHITECTURE.md
View File

0
CHANGELOG.md
View File

80
COMMON_APPLICATIONS.md
View File

@ -1,80 +0,0 @@
# Common Applications
This section outlines the common applications tailored for both servers and end-users, offering a wide range of functionalities to enhance system performance, security, and usability.
## Base Setup
Key for initial system configuration, this section includes hostname setting, systemd journal management, locale configurations, and swapfile handling. Essential for both server and end-user setups, it ensures a solid foundation for system operations.
- **[Hostname](roles/hostname/)**: Sets the system's hostname.
- **[Journalctl](./roles/journalctl/)**: Configures systemd journal settings.
- **[Locales](./roles/locales/)**: Configures system locales.
- **[System-Swapfile](./roles/system-swapfile/)**: Configures swapfile creation and management.
## Administration Tools
These tools are crucial for effective system administration, encompassing Git setup, Linux admin tools, and sudo configuration, suitable for both server environments and power users.
- **[Git](./roles/git/)**: Basic Git version control system setup.
- **[Administrator-Tools](./roles/pc-administrator-tools/)**: Installs basic Linux administration tools.
- **[Sudo](./roles/sudo/)**: Installs and configures sudo.
## Update
This category focuses on automated updates and maintenance for the system and its components, including package managers and Docker containers, ensuring systems are up-to-date and secure.
- **[update](./roles/update/)**: Automates the process of system updates.
- **[update-apt](./roles/update-apt/)**: Updates system packages using apt (for Debian-based systems).
- **[update-docker](./roles/update-docker/)**: Keeps Docker containers up to date.
- **[update-pacman](./roles/update-pacman/)**: Updates system packages using Pacman (for Arch-based systems).
- **[update-yay](./roles/update-yay/)**: Updates system packages using yay.
## Driver
Caters to a range of devices and needs for hardware driver installation and configuration, an integral part for both server hardware optimization and end-user device functionality.
- **[driver-epson-multiprinter](./roles/driver-epson-multiprinter/)**: Installs drivers for Epson multi-function printers.
- **[driver-intel](./roles/driver-intel/)**: Installs Intel drivers, typically for graphics and other hardware.
- **[driver-msi-keyboard-color](./roles/driver-msi-keyboard-color/)**: Configures MSI keyboard color settings.
- **[driver-non-free](./roles/driver-non-free/)**: Installs non-free drivers, generally for specific hardware needs.
## Security
Enhances system security with roles focused on security measures, user configurations, and SSH settings. It's vital for protecting both server environments and end-user systems.
- **[System Security](./roles/system-security/)**: Enhances overall system security.
- **[User Administrator](./roles/user-administrator/)**: Setup for system administrator user.
- **[PC SSH](./roles/pc-ssh/)**: Configuration of SSH for secure remote access.
- **[SSHD](./roles/sshd/)**: Configures SSH daemon settings.
- **[System Maintenance Lock](./roles/system-maintenance-lock)**: Locks maintenance services to prevent dangerous inteactions between services
## Virtual Private Network (VPN)
Centers on VPN configurations for secure and efficient network connectivity, particularly crucial for remote server access and end-users needing secure connections.
- **[client-wireguard](./roles/client-wireguard/)**: Configures Wireguard VPN client.
- **[client-wireguard-behind-firewall](./roles/client-wireguard-behind-firewall/)**: Sets up Wireguard client functionality behind a firewall.
- **[wireguard](./roles/wireguard/)**: Installs and configures Wireguard for secure VPN connections.
## Notifier
Sets up system event notifications via email and Telegram, a versatile feature for server administrators and end-users alike to stay informed about their system's status.
- **[Systemd-Notifier](./roles/systemd-notifier/)**: Notifier service for systemd.
- **[Systemd-Notifier-Email](./roles/systemd-notifier-email/)**: Email notifications for systemd services.
- **[Systemd-Notifier-Telegram](./roles/systemd-notifier-telegram/)**: Telegram notifications for systemd services.
## Backup Solutions
Focuses on comprehensive backup strategies and cleanup procedures, encompassing data backups, remote server backups, and maintenance of backup storage efficiency, crucial for data integrity in both servers and personal devices.
### Backups
For USB devices, Docker volumes, remote servers, and user configurations.
- **[backup-data-to-usb](./roles/backup-data-to-usb/)**: Automates data backup to USB devices.
- **[backup-docker-to-local](./roles/backup-docker-to-local/)**: Backs up Docker volumes to local storage.
- **[backup-remote-to-local](./roles/backup-remote-to-local/)**: Pulls backups from remote servers for local storage.
- **[backups-provider](./roles/backups-provider/)**: Manages backup processes and storage solutions.
- **[backups-provider-user](./roles/backups-provider-user/)**: Creates and configures users for backup processes.
### Backups Cleanup
Manages disk space and cleans up old or failed backups.
- **[cleanup-backups-service](./roles/cleanup-backups-service/)**: Service to clean up old backups automatically.
- **[cleanup-backups-timer](./roles/cleanup-backups-timer/)**: Timer for scheduling the backup cleanup service.
- **[cleanup-disc-space](./roles/cleanup-disc-space/)**: Manages and frees up disk space on the system.
- **[cleanup-failed-docker-backups](./roles/cleanup-failed-docker-backups/)**: Cleans up failed Docker backups.
## Other
Encompasses miscellaneous essential tools and systems, including package management, spellchecking, and typesetting, beneficial for both server maintenance and enhancing end-user experience.
- **[System-Aur-Helper](./roles/system-aur-helper/)**: Installs and configures AUR helper (yay).
- **[Hunspell](./roles/hunspell/)**: Installation of Hunspell spellchecker.
- **[Latex](./roles/pc-latex/)**: Installation of LaTeX typesetting system.
- **[Java](./roles/java/)**: Installs Java Development Kit (JDK).
- **[Python Pip](./roles/python-pip/)**: Installation of Python Pip package manager.

0
CONTRIBUTING.md
View File

46
END_USER_APPLICATIONS.md
View File

@ -1,46 +0,0 @@
# End User Applications
End User Applications provide a diverse suite of tools and software designed to enhance the computing experience for personal computer users, including those using desktops and laptops. These applications cover various aspects such as multimedia, productivity, virtualization, and more, catering to the everyday needs of end users.
## Common Applications
In addition to the specialized software found in this document, the [COMMON_APPLICATIONS.md](./COMMON_APPLICATIONS.md) offers a comprehensive range of functionalities that cater to both server and end-user needs. This section enhances system performance, security, and usability with a variety of tools and configurations suitable for diverse computing environments.
## Desktop
This category focuses on tools and configurations that enhance the desktop computing experience. It includes utilities to maintain system activity, and software for optimizing the desktop environment, ensuring a seamless and user-friendly interface for day-to-day computer usage.
- **[Caffeine](./roles/pc-caffeine/)**: Utility to keep your computer awake.
- **[Gnome](./roles/pc-gnome/)**: Installation and configuration of Gnome desktop environment.
## Entertainment
Geared towards leisure and entertainment, this section includes software for playing Blu-ray media, accessing a vast collection of music, and installing various computer games. It's designed to enrich your personal computing experience with multimedia enjoyment and gaming.
- **[Bluray Player Tools](./roles/pc-bluray-player-tools/)**: Software for playing Blu-ray media on personal computers.
- **[Spotify](./roles/pc-spotify/)**: Installation of Spotify for music streaming.
- **[Games](./roles/pc-games/)**: Installation of various computer games.
## Office
This segment caters to professional productivity needs. It encompasses a range of office-related software, from comprehensive office suites and video conferencing tools to cloud storage solutions, facilitating efficient and organized work in various office environments.
- **[LibreOffice](./roles/pc-libreoffice/)**: Installation of the LibreOffice suite.
- **[Office](./roles/pc-office/)**: Various office productivity tools.
- **[Video Conference](./roles/pc-video-conference/)**: Video conferencing software setup.
- **[Nextcloud Client](./roles/pc-nextcloud/)**: Client setup for Nextcloud cloud storage service.
- **[GnuCash](./roles/pc-gnucash/)**: Software to manage finances
- **[Jrnl](./roles/pc-jrnl/)**: CLI Journaling
## Anonymization
Focusing on privacy and security, the Anonymization section offers tools for secure file sharing and anonymous web browsing. It includes software solutions that prioritize user privacy, ensuring secure online activities and data protection.
- **[Qbittorrent](./roles/pc-qbittorrent/)**: Installation of qBittorrent for file sharing.
- **[Torbrowser](./roles/pc-torbrowser/)**: Installation of Tor Browser for anonymous browsing.
## Content Creation
Dedicated to creatives and content producers, this category provides tools essential for video streaming, recording, graphic design, and 3D modeling. It's tailored for those involved in digital content creation, offering the necessary software to bring creative projects to life.
- **[Streaming Tools](./roles/pc-streaming-tools/)**: Software for video streaming and recording.
- **[Designer Tools](./roles/pc-designer-tools/)**: Graphic design and 3D modeling software.
## Development Environment
Targets software developers with tools and environments for various programming languages and development needs.
- **[Developer Tools](./roles/pc-developer-tools/)**: Basic developer tools setup.
- **[Developer Tools for Arduino](./roles/pc-developer-tools-arduino/)**: Setup for Arduino development.
- **[Developer Tools for Bash](./roles/pc-developer-tools-bash/)**: Tools for Bash scripting.
- **[Developer Tools for Java](./roles/pc-developer-tools-java/)**: Java development environment setup.
- **[Developer Tools for PHP](./roles/pc-developer-tools-php/)**: PHP development environment setup.
- **[Developer Tools for Python](./roles/pc-developer-tools-python/)**: Python development environment setup.
- **[Virtual Box](./roles/pc-virtual-box/)**: VirtualBox setup for creating virtual machines.
- **[Network Analyze Tools](./roles/pc-network-analyze-tools/)**: Network analysis and troubleshooting utilities.

0
FAQ.md
View File

0
INSTALLATION.md
View File

19
README.md
View File

@ -24,19 +24,7 @@ Leveraging the power of Open Source, our tool not only promises to uphold the hi
This is not just a step towards simplifying IT management – it's a leap towards democratizing access to advanced technology, ensuring every business can quickly adapt and thrive in the digital age.
For a deeper understanding of our goals and the ethos driving our project, we invite you to explore our detailed **[Vision Statement](./VISION_STATEMENT.md)**. Here, you'll find the cornerstone principles that guide our development process and our commitment to making a lasting impact in the realm of IT infrastructure.
### Solutions Overview
To help you navigate through our repository, we have categorized our extensive range of tools and solutions into three key areas:
1. **[Server Applications](./SERVER_APPLICATIONS.md)**: Detailed information on server-focused tools and configurations, ideal for managing and optimizing server environments.
2. **[End User Applications](./END_USER_APPLICATIONS.md)**: A guide to applications and tools specifically designed for end-user PCs, enhancing personal computing experience.
3. **[Common Applications](./COMMON_APPLICATIONS.md)**: A comprehensive list of tools and applications that are versatile and useful across both server and end-user environments.
Each of these documents provides a tailored overview, ensuring you can find the right tools and information relevant to your specific needs, whether for server management, personal computing, or general IT infrastructure.
For a deeper understanding of our goals and the ethos driving our project, we invite you to explore our detailed **[Vision Statement](./VISION.md)**. Here, you'll find the cornerstone principles that guide our development process and our commitment to making a lasting impact in the realm of IT infrastructure.
## Key Benefits of CyMaIS for Your Business
@ -73,11 +61,6 @@ Contact me for more details:
📧 Email: [kevin@veen.world](mailto:kevin@veen.world)<br />
☎️ Phone: [+ 49 178 179 80 23](tel:00491781798023)
### Showcases
The following list showcases the extensive range of solutions that CyMaIS incorporates, each playing a vital role in providing a comprehensive, efficient, and secure IT infrastructure setup:
[ELK Stack](./roles/docker-elk), [Intel Driver](./roles/driver-intel), [Nginx Docker Reverse Proxy](./roles/nginx-docker-reverse-proxy), [Sudo](./roles/sudo), [Funkwhale](./roles/docker-funkwhale), [MSI Keyboard Color Driver](./roles/driver-msi-keyboard-color), [Nginx Domain Redirect](./roles/nginx-redirect-domain), [GnuCash](./roles/pc-gnucash), [Backup Data to USB](./roles/backup-data-to-usb), [Gitea](./roles/docker-gitea), [Non-Free Driver](./roles/driver-non-free), [Nginx Homepage](./roles/nginx-serve-html), [Jrnl](./roles/pc-jrnl), [Systemd Notifier](./roles/systemd-notifier), [Backup Docker to Local](./roles/backup-docker-to-local), [Jenkins](./roles/docker-jenkins), [Git](./roles/git), [Nginx HTTPS](./roles/nginx-https), [Latex](./roles/pc-latex), [Email Notifier](./roles/systemd-notifier-email), [Remote to Local Backup Solution](./roles/backup-remote-to-local), [Joomla](./roles/docker-joomla), [Heal Defect Docker Installations](./roles/heal-docker), [Nginx Matomo Tracking](./roles/nginx-modifier-matomo), [LibreOffice](./roles/pc-libreoffice), [Telegram Notifier](./roles/systemd-notifier-telegram), [Listmonk](./roles/docker-listmonk), [Btrfs Health Check](./roles/health-btrfs), [Nginx WWW Redirect](./roles/nginx-redirect-www), [Network Analyze Tools](./roles/pc-network-analyze-tools), [System Security](./roles/system-security), [Mailu](./roles/docker-mailu), [Disc Space Health Check](./roles/health-disc-space), [Administrator Tools](./roles/pc-administrator-tools), [Nextcloud Client](./roles/pc-nextcloud), [Swapfile Setup](./roles/system-swapfile), [Backups Cleanup](./roles/cleanup-backups-service), [Mastodon](./roles/docker-mastodon), [Docker Container Health Checker](./roles/health-docker-container), [Blu-ray Player Tools](./roles/pc-bluray-player-tools), [Office](./roles/pc-office), [Update Solutions](./roles/update), [Matomo](./roles/docker-matomo), [Docker Volumes Health Checker](./roles/health-docker-volumes), [Caffeine](./roles/pc-caffeine), [Qbittorrent](./roles/pc-qbittorrent), [Update Apt](./roles/update-apt), [Disc Space Cleanup](./roles/cleanup-disc-space), [Matrix](./roles/docker-matrix), [Health Journalctl](./roles/health-journalctl), [Designer Tools](./roles/pc-designer-tools), [Security Tools](./roles/pc-security-tools), [Update Docker](./roles/update-docker), [Failed Docker Backups Cleanup](./roles/cleanup-failed-docker-backups), [MediaWiki](./roles/docker-mediawiki), [Nginx Health Checker](./roles/health-nginx), [Developer Tools](./roles/pc-developer-tools), [Spotify](./roles/pc-spotify), [Update Pacman](./roles/update-pacman), [Client Wireguard](./roles/client-wireguard), [MyBB](./roles/docker-mybb), [Developer Tools for Arduino](./roles/pc-developer-tools-arduino), [SSH](./roles/pc-ssh), [Update Yay](./roles/update-yay), [Client Setup for Wireguard Behind Firewall](./roles/client-wireguard-behind-firewall), [Nextcloud Server](./roles/docker-nextcloud), [Hunspell](./roles/hunspell), [Developer Tools for Bash](./roles/pc-developer-tools-bash), [Streaming Tools](./roles/pc-streaming-tools), [Administrator](./roles/user-administrator), [Docker](./roles/docker), [Peertube](./roles/docker-peertube), [Java](./roles/java), [Developer Tools for Java](./roles/pc-developer-tools-java), [Tor Browser](./roles/pc-torbrowser), [Video Conference](./roles/pc-video-conference), [Wireguard](./roles/wireguard), [Akaunting](./roles/docker-akaunting), [Pixelfed](./roles/docker-pixelfed), [Journalctl](./roles/journalctl), [Developer Tools for PHP](./roles/pc-developer-tools-php), [Virtual Box](./roles/pc-virtual-box), [Postfix](./roles/postfix), [Attendize](./roles/docker-attendize), [Wordpress](./roles/docker-wordpress), [Locales](./roles/locales), [Docker for End Users](./roles/pc-docker), [Games](./roles/pc-games), [Python Pip](./roles/python-pip), [Discourse](./roles/docker-discourse), [Epson Multiprinter Driver](./roles/driver-epson-multiprinter), [Nginx Certbot](./roles/nginx-certbot), [Git](./roles/pc-git), [SSHD](./roles/sshd), [YOURLS](./roles/docker-yourls), [BigBlueButton](./roles/docker-bigbluebutton),[System Maintenance Lock](./roles/system-maintenance-lock),[Open Project](./roles/docker-openproject)...
### License
This project is licensed from Kevin Veen-Birkenbach. The full license is available in the [LICENSE.md](./LICENSE.md) of this repository.

0
SECURITY.md
View File

96
SERVER_APPLICATIONS.md
View File

@ -1,96 +0,0 @@
# Server Applications
Server applications encompass a wide array of functionalities designed to enhance the performance, reliability, and usability of server infrastructures. These applications are essential for maintaining server health, managing web services, facilitating containerization, and providing various tools for specific server needs.
## Common Applications
For a detailed overview of the broad spectrum of server applications, including base setup, administration tools, update mechanisms, driver installations, security enhancements, VPN configurations, notifier services, backup solutions, and other essential tools and systems, please refer to the **[COMMON_APPLICATIONS.md](./COMMON_APPLICATIONS.md)**. This document provides insights into categories and specific roles catered to both server and end-user environments, ensuring comprehensive server management and optimization.
## Server Health
Addresses server maintenance and health monitoring, ensuring optimal performance and reliability of the server infrastructure.
- **[Health Btrfs](./roles/health-btrfs/)**: Monitors the health of Btrfs filesystems.
- **[Health Disc Space](./roles/health-disc-space/)**: Checks for available disk space.
- **[Health Docker Container](./roles/health-docker-container/)**: Monitors the health of Docker containers.
- **[Health Docker Volumes](./roles/health-docker-volumes/)**: Checks the status of Docker volumes.
- **[Health Journalctl](./roles/health-journalctl/)**: Monitors and manages the system journal.
- **[Health Nginx](./roles/health-nginx/)**: Ensures the Nginx server is running smoothly.
- **[Heal Docker](./roles/heal-docker/)**: Automated healing and maintenance tasks for Docker.
## Webserver
Focuses on web server roles and applications, covering SSL certificates, Nginx configurations, reverse proxies, and email services.
- **[Letsencrypt](./roles/letsencrypt/)**: Configures Let's Encrypt for SSL certificates.
- **[Nginx](./roles/nginx/)**: Installs and configures Nginx web server.
- **[Nginx-Docker-Reverse-Proxy](./roles/nginx-docker-reverse-proxy/)**: Sets up a reverse proxy for Docker containers.
- **[nginx-serve-html](./roles/nginx-serve-html/)**: Configures a homepage for Nginx.
- **[Nginx-Https](./roles/nginx-https/)**: Enables HTTPS configuration for Nginx.
- **[nginx-modifier-matomo](./roles/nginx-modifier-matomo/)**: Integrates Matomo tracking with Nginx.
- **[nginx-redirect-domain](./roles/nginx-redirect-domain/)**: Manages URL redirects in Nginx.
- **[nginx-redirect-www](./roles/nginx-redirect-www/)**: Redirects all domains with the prefix www. from www.domain.tld to domain.tld
- **[Nginx-Certbot](./roles/nginx-certbot/)**: Integrates Certbot with Nginx for SSL certificates.
- **[Postfix](./roles/postfix/)**: Setup for the Postfix mail transfer agent.
## Docker and Containerization
Dedicated to Docker container setups and application management, offering a wide array of software deployment options.
- **[Docker](./roles/docker/)**: Basic Docker and Docker Compose setup.
### Finance and Project Management
Facilitating the deployment of finance-related and project management applications.
- **[Docker Akaunting](./roles/docker-akaunting/)**: Deployment of the Akaunting finance software.
- **[Open Project](./roles/docker-openproject)**: Project Management Software
- **[Taiga](./roles/docker-taiga)**: Scrum and Kanban Software
### Continues Integration and Continues Delivery
Setups for development platforms and version control systems.
- **[Gitea](./roles/docker-gitea/)**: Setup for the Gitea git server.
- **[Jenkins](./roles/docker-jenkins/)**: Jenkins automation server setup.
- **[ELK](./roles/docker-elk/)**: Elasticsearch, Logstash, and Kibana (ELK) stack setup.
### Content Management
Deployment of various content management systems for web platforms.
- **[Wordpress](./roles/docker-wordpress/)**: Wordpress blog and website platform setup.
- **[Joomla](./roles/docker-joomla/)**: Joomla content management system setup.
### Fediverse Networks
Implementing federated and decentralized social platforms.
- **[Funkwhale](./roles/docker-funkwhale/)**: Deployment of Funkwhale, a federated music streaming server.
- **[Mastodon](./roles/docker-mastodon/)**: Deployment of the Mastodon social network server.
- **[Peertube](./roles/docker-peertube/)**: Deployment of the PeerTube video platform.
- **[Pixelfed](./roles/docker-pixelfed/)**: Pixelfed, a federated image sharing platform, setup.
### Analytics Solutions
Tools for web and data analytics.
- **[Matomo](./roles/docker-matomo/)**: Setup for Matomo, an open-source analytics platform.
### Forum Software
Deployments for community-driven forum platforms.
- **[MyBB](./roles/docker-mybb/)**: Setup for MyBB forum software.
- **[Discourse](./roles/docker-discourse/)**: Setup of Discouse a forum and community platform.
### Wiki and Documentation
Setting up platforms for collaborative information sharing.
- **[MediaWiki](./roles/docker-mediawiki/)**: MediaWiki setup for creating wikis.
### Event and Shop Management
Tools for managing events and online retail.
- **[Attendize](./roles/docker-attendize/)**: Setup for the Attendize event management tool.
### Data and Cloud Storage
Solutions for data management and cloud-based storage.
- **[Baserow](./roles/docker-baserow/)**: Deployment of Baserow, an open-source no-code database tool.
- **[Nextcloud](./roles/docker-nextcloud/)**: Cloud storage solution setup.
### Communication and Collaboration
Platffor enhancing communication and collaborative efforts.
- **[BigBlueButton](./roles/docker-bigbluebutton/)**: Setup for the BigBlueButton video conferencing tool.
- **[Mailu](./roles/docker-mailu/)**: Complete mail server solution.
- **[Matrix](./roles/docker-matrix/)**: Setup and deployment of the Matrix server for secure, decentralized communication.
### Marketing and Communication Tools
Focusing on tools that assist in communication, marketing, and outreach efforts.
- **[Listmonk](./roles/docker-listmonk/)**: Setup for Listmonk, a self-hosted newsletter and mailing list manager.
### Web Utilities and Services
Encompassing tools that enhance web functionality or provide essential web services.
- **[YOURLS](./roles/docker-yourls/)**: Setup for YOURLS, a URL shortening service.
### Miscellaneous
Diverse tools for specific needs and utilities.
- **[Roulette Wheel](./roles/docker-roulette-wheel/)**: Setup for a custom roulette wheel application.

0
USAGE.md
View File

3
requirements.txt Normal file
View File

@ -0,0 +1,3 @@
myst-parser
sphinx
sphinx-rtd-theme

4
reuirements.yml
View File

@ -1,4 +0,0 @@
pip:
myst-parser
sphinx
sphinx-rtd-theme

4
roles/README.md
View File

@ -1,2 +1,2 @@
# Hello World
test
# Echo
Hello World

8
roles/index.rst
View File

@ -1,11 +1,11 @@
Applications and Roles
===========================================================
.. include:: ./README.md
:parsers: myst_parser
.. markdown-include:: README.md
.. toctree::
:maxdepth: 1
:caption: Overview
:caption: About CyMaIS:
:glob:
./*.rst
*.rst

2
roles/restart-docker/README.md
View File

@ -24,7 +24,7 @@ The primary purpose of this role is to ensure that all Docker Compose services a
# Context
This role was implemented to address the classic issue: ["Have you tried turning it off and on again?"](https://www.youtube.com/watch?v=rksCTVFtjM4). The problem initially arose with the `fetchmail` container in [Mailu](../roles/docker/mailu), which fails if only some containers, and not the full docker-compose composition, are restarted.
This role was implemented to address the classic issue: ["Have you tried turning it off and on again?"](https://www.youtube.com/watch?v=rksCTVFtjM4). The problem initially arose with the `fetchmail` container in [Mailu](.roles/docker/mailu), which fails if only some containers, and not the full docker-compose composition, are restarted.
## Credits 📝
This role was developed with the assistance of [ChatGPT](https://openai.com/chatgpt), including insights and optimizations from this [conversation](https://chatgpt.com/share/674c6870-fcc4-800f-a19e-b20621b24317). Special thanks for providing guidance on error handling, Ansible best practices, and Python integration.

12
sphinx/conf.py
View File

@ -55,6 +55,7 @@ extensions = [
"myst_parser",
'local_md_files',
'roles_overview',
'markdown_include',
]
autosummary_generate = True
@ -63,3 +64,14 @@ myst_enable_extensions = [
"colon_fence", # Für erweiterte Syntax wie ::: Hinweisboxen etc.
# weitere Erweiterungen nach Bedarf
]
def setup(app):
python_domain = app.registry.domains.get('py')
if python_domain is not None:
directive = python_domain.directives.get('currentmodule')
if directive is not None:
directive.optional_arguments = 10
return {'version': '1.0', 'parallel_read_safe': True}

53
sphinx/markdown_include.py Normal file
View File

@ -0,0 +1,53 @@
import os
from docutils import nodes
from docutils.parsers.rst import Directive
from sphinx.util import logging
logger = logging.getLogger(__name__)
from myst_parser.parsers.sphinx_ import MystParser
class MarkdownIncludeDirective(Directive):
required_arguments = 1 # Pfad zur Markdown-Datei
optional_arguments = 0
final_argument_whitespace = True
has_content = False
def run(self):
logger.info("markdown-include-Direktive wird ausgeführt")
env = self.state.document.settings.env
# Ermittle den absoluten Pfad der Datei.
rel_filename, filename = env.relfn2path(self.arguments[0])
logger.info("Markdown-Datei: %s", filename)
if not os.path.exists(filename):
error = self.state_machine.reporter.error(
f'File not found: {filename}',
nodes.literal_block(self.block_text, self.block_text),
line=self.lineno)
return [error]
try:
with open(filename, 'r', encoding='utf-8') as f:
markdown_content = f.read()
except Exception as e:
error = self.state_machine.reporter.error(
f'Error reading file {filename}: {e}',
nodes.literal_block(self.block_text, self.block_text),
line=self.lineno)
return [error]
# Parse den Markdown-Content mit MystParser.
parser = MystParser()
from docutils.frontend import OptionParser
from docutils.utils import new_document
settings = OptionParser(components=(MystParser,)).get_default_values()
# Hänge die Sphinx-Umgebung an die Einstellungen an, damit myst_parser funktioniert.
settings.env = self.state.document.settings.env
doc = new_document(filename, settings=settings)
parser.parse(markdown_content, doc)
logger.info("Markdown-Parsing erfolgreich abgeschlossen")
return doc.children
def setup(app):
app.add_directive("markdown-include", MarkdownIncludeDirective)
return {'version': '0.1', 'parallel_read_safe': True}

1
sphinx/roles_overview.py
View File

@ -60,7 +60,6 @@ class RolesOverviewDirective(Directive):
categories.setdefault(tag, []).append(role_entry)
else:
logger.warning(f"meta/main.yml not found for role {role_path}")
logger.info("For role %s, galaxy_info: %s", role_name, galaxy_info)
# Sort categories and roles alphabetically.
sorted_categories = sorted(categories.items(), key=lambda x: x[0].lower())