--- title: Quarto Renderer (index.qmd + project sheets) --- # Specification: Quarto Renderer (index.qmd + project sheets) This document formalises the structure of the Quarto artefacts generated by the *GitLab-Overview* pipeline. The renderer emits one **site root** file (`index.qmd`) and a collection of **per-project** `.qmd` sheets organised in sub-directories that mirror GitLab groups. The output is meant to compile with Quarto for publishing on Confluence via the built-in `confluence-html` format. --- ## 1. Directory & Naming Conventions ```text quarto/ index.qmd ← overview landing page / ← one directory per GitLab group (slug derived from group.path) .qmd ← individual project sheet … ``` * `group-dir` derives from `group.path`. * `project-slug` derives from `project.path_with_namespace`. * Some groups may have subgroups. This is reflected in the directory-structure. `project.path_with_namespace` has the complete structure for each project. --- ## 2. `index.qmd` ### 2.1 YAML Front-Matter ```yaml --- title: "Gitlab-Übersicht" format: confluence-html toc: true --- ``` * **No additional keys** are added without explicit specification; stability of diff against snapshot is critical. * The built-in `toc: true` replaces the manual `[[TOC]]` marker used in the Markdown renderer. ### 2.2 Summary Section The section follows the same rules as in [Markdown Overview Renderer](./spec_renderer_markdown.md). ```markdown ## Summary ### ### … ``` * The table follows all rules in [Table Rendering & UI](./spec_table_rendering_ui.md) (m-dash placeholder, custom labels …). * **Repository column** value is a Markdown link to the project's sheet (`/.qmd`). If an avatar is available the link text is preceded by `![Avatar](){width=16px}`. * The explanatory note is a fixed sentence: > Note: If no supervisors were found, authors of the README are named as supervisors. * Blank line between note and next `###` heading. ### 2.3 Detailed Section After the last summary table the renderer appends **one** detailed section for every project, grouped by the same GitLab group order: ```markdown ## Group ### ### … ``` Ordering: * Groups appear in the same order as in the summary section. * Projects keep their summary-table order. #### 2.3.1 Project details block The section follows the same rules as in [Markdown Overview Renderer](./spec_renderer_markdown.md) with the only difference being the internal link to the full readme. Both have to stay in sync for all other aspects. 1. **Description list** with up to three entries in this order – `Date`, `Status`, `Supervisors` – each on its own line in *definition-list* syntax: ```markdown Date : 2025-06-18 Supervisors : Marty McFly : Doctor Brown ``` If `Supervisors` are not Available it is substituded by `Authors` like so: ```markdown Date : 2025-06-18 Authors : Marty McFly : Doctor Brown ``` Missing entries from the Project-Info are omitted. 2. **Release badge** – image linking to `/-/releases`. 3. **Description callout** titled *Description* with (first applicable) * If frontmatter has a description-key: callout-type `tip` and content frontmatter["description"] * If `Readme.content` is not `None` or empty: callout-type `warning` and contend from `Readme.content` * The content is truncated to the first 10 non-blank lines. If the original content is longer, it is appended with `…continues…`. This truncation is applied to the plain text before any markdown rendering. * If `Readme.content` is `None`: callout-type `danger` and content "No Readme found" 4. **Issues callout** titled *Open Issues* containing bullet list items, each item is a link to the GitLab issue. After the list one `TOTAL:` line summarises `opened` and `closed` counts. 5. Final paragraph: `[Link to full readme](/.qmd)` linking to the generated project-sheet. Blank lines separate each logical part; no extra thematic breaks. --- ## 3. Per-Project Sheet (`[/subgroups/..]/.qmd`) ### 3.1 YAML Front-Matter ```yaml --- title: " ()" format: confluence-html: code-links: - text: GitLab href: icon: gitlab --- ``` * Only the `code-links` array is mandated; additional Quarto keys require a spec update. ### 3.2 Body Structure ```markdown # () > [!note] README > > --- ← the complete README > title: ... > author: ... > date: ... > ... ## Issues ### Status: … (repeat per issue) ``` * The first element is an H1 mirroring the file title. * Immediately afterwards in an Obsidian-style callout the whole Readme gets quoted with its markdown-content. * Remaining content are all issues still open (or the string `No open Issues` after the H2 heading) --- ## 4. Placeholder Rules & Encodings * Missing numeric / text values in tables are rendered as m-dash `—`. * Dates are formatted `YYYY-MM-DD`. * Dates can come from multiple sources. Priority is: `Project.last_activity_at` > `Readme.extra.raw_frontmatter["date"]` > Em-Dash fallback. * Release badge URLs, avatar images and issue links are taken verbatim from GitLab meta data; renderer does not rewrite them. --- ## 5. Compatibility Contract * `index.qmd` plus all project sheets generated **must** compile with `quarto render` without warnings. * For regression tests, rendering *single* group "Alpha Group" from @gold_data/ must produce output identical to `tests/snapshots/quarto_renderer_single.qmd`. * Any deliberate deviation requires a snapshot update and changelog entry. --- ## 6. Error Handling | Situation | Behaviour | |-----------|-----------| | README missing | Project sheet still generated; `[!note]`-callout becomes a `[!warning] No README found!` | | Release badge URL unreachable | Badge image is still emitted (broken link tolerated). | | Issues API returns error | Omit issues callout; do **not** fail rendering. | --- ## 7. Relationship to Other Specifications * Table cells & ordering rules follow [Table Rendering & UI](./spec_table_rendering_ui.md) and [Table Sorting](./spec_table_sorting.md). * Source data is provided by [Data Collector](./spec_data_collector.md) and mapped via [Model Mapping](./spec_model_mapping.md). --- ## 8. Implementation Interface (Class-based Contract) All Quarto renderers must implement a class-based interface as follows: - Inherit from the abstract base class `Renderer` (see `src/gitlab_overviewer/rendering/renderer_base.py`). - Implement the following methods: - `render(self, overview_data, ...) -> str`: Render the output as a string. - `write_files(self, overview_data, ...) -> None`: Write the rendered output to files as specified. - Render-agnostic helpers (e.g., placeholder handling, star rating, safe conversion) are provided as `@staticmethod`s on `Renderer` and should be used by all subclasses. **Rationale:** - This contract enforces consistency and extensibility for all renderers. - It enables robust testing, code reuse, and future support for additional output formats (e.g., HTML, PDF). - The interface is enforced in code and validated by the test suite. This is an internal code structure requirement and does not affect the output format, but all new renderers must comply. **Open Questions:** - Should future renderers (e.g., HTML, PDF) follow this interface? (TBD) - Are there additional common methods that should be included in the base interface? (TBD) - See TODOs in `Renderer` base class for possible candidates.