How swablab/documents works
Project's Main Purpose and Components
• Purpose: The repository holds a set of document templates (with extension .typ) meant to be processed by Typst to generate official documents (such as spendenbescheinigung, protokoll, rechnung, etc.). It also includes configuration templates (.yml.template) for some documents, and tools for development automation.
• Main Components:
• Document Templates: These are the Typst files (e.g., spendenbescheinigung.typ, protokoll.typ) along with related YAML template files used for configuration.
• Common Template Directory: The "templates" folder contains shared template parts (e.g., common.typ, tmpl_doc.typ) that provide a reusable structure for various documents.
• Build and Execution Environment: This includes the Devcontainer configuration (.devcontainer folder), the Containerfile (for containerization), and VSCode settings (.vscode directory) that ensure consistency and automation in the development environment.
• CI/CD/Automation: The Forgejo workflows (inside the .forgejo/workflows directory) manage deployment or automated tasks like building or testing the templates.
• External Dependencies: Typst as the document compiler and external fonts (Noto and Ubuntu) are required to properly render the PDFs.
Relationships and Interactions
• Developers create or modify the Typst document files and their corresponding YAML configuration templates.
• When a change is made, the local development environment (using VSCode and Devcontainers) leverages the Containerfile configuration to provide a consistent Typst environment with all necessary fonts installed.
• The Typst compiler is then used (via commands shown in the README) to compile the template files into PDFs.
• The Forgejo CI/CD pipelines may pick up changes in the repository to automate tasks like deployment or further testing of the document generation process.
• The design also shows reusability: the "templates" folder provides common components that individual document templates include (via import mechanisms in Typst).
Architectural Patterns and Design Principles
• Modular Design: Each document template is a separate component that can reference common template blocks, making the system modular.
• Separation of Concerns: The system separates raw document content (the .typ files), configuration (YAML templates), and environment/setup (Devcontainer, Containerfile, VSCode configuration).
• DevOps Integration: The inclusion of CI/CD workflows in Forgejo shows a move towards automation and continuous integration in document generation.