Add documentation packages for the project's libraries to the mise config #21

New issue

Closed

opened 2026-11-13 10:53:48 +01:00 by omp-deck · 0 comments

omp-deck commented

2026-11-13 10:53:48 +01:00

Collaborator

Problem

The project's libraries are consumed as C/C++ APIs (wp/*, pipewire/keys.h, glib.h/glib-unix.h, RtMidi.h), but no API documentation is available in a development environment provisioned from this repository's mise config. A reader has the headers declared and nothing to read beside them, so questions like "does WirePlumber 0.5 emit a signal for node property changes" cannot be answered locally and end up guessed or abandoned.

mise.toml already declares a -dev package for every library the code includes, so the headers side needs no change; libspa-0.2-dev arrives automatically as a hard dependency of libpipewire-0.3-dev. What is missing is the matching -doc packages.

Plan

Add the documentation packages to `[bootstrap.packages]`

Edit the tracked mise.toml only. Do not touch mise.local.toml: it is untracked, carries the header # Managed by omp-deck — edited in Settings → Workspaces. Local edits are overwritten., and is regenerated from a setting outside this repository.

Append a new commented block at the end of [bootstrap.packages] (the table currently ends with "apt:libmagicenum-dev" = "latest"), matching the file's existing style of a short comment line above each group:

# API documentation for the libraries above
"apt:wireplumber-doc" = "latest"
"apt:libglib2.0-doc" = "latest"
"apt:pipewire-doc" = "latest"
"apt:librtmidi-doc" = "latest"
"apt:libasound2-doc" = "latest"

Use these package names verbatim. All five exist in Debian trixie at versions matching the declared -dev packages: wireplumber-doc 0.5.8-2, libglib2.0-doc 2.84.4-3~deb13u5, pipewire-doc 1.4.2-1, librtmidi-doc 6.0.0-2, libasound2-doc 1.2.14-1+deb13u1. "latest" matches the version value every existing entry in the table uses.

Keep all existing entries, including every -dev entry, unchanged. Do not add libspa-0.2-dev: libpipewire-0.3-dev depends on it (dep: libspa-0.2-dev (= 1.4.2-1)), so it is already pulled in.

Nothing else changes: no README section, no CMake change, no new file. The ten existing package entries and the [tools], [env] and [bootstrap.apt.sources.trixie-backports] tables are untouched.

Verification

From the repository root:

mise bootstrap status

The output must list all five new entries as packages apt:<name> … lines — for example packages apt:wireplumber-doc missing — alongside the pre-existing ones. Each line proves two things at once: the TOML still parses (a syntax error makes the command fail instead of listing anything), and mise recognises each new key as a package entry rather than silently dropping it. The missing / installed state itself is not part of the acceptance criterion; an environment that has not installed them yet still passes.

Installing the packages is out of scope for this change, so no check asserts that files appear under /usr/share/doc/.

Assumptions & contingencies

mise bootstrap status is expected to run without privileges and without network access, as a read-only report. If it instead fails for a reason unrelated to this edit (for example no apt lists available), fall back to proving the edit with mise config get bootstrap.packages and confirm the five keys appear in its output; do not attempt to install anything.

## Problem The project's libraries are consumed as C/C++ APIs (`wp/*`, `pipewire/keys.h`, `glib.h`/`glib-unix.h`, `RtMidi.h`), but no API documentation is available in a development environment provisioned from this repository's mise config. A reader has the headers declared and nothing to read beside them, so questions like "does WirePlumber 0.5 emit a signal for node property changes" cannot be answered locally and end up guessed or abandoned. `mise.toml` already declares a `-dev` package for every library the code includes, so the headers side needs no change; `libspa-0.2-dev` arrives automatically as a hard dependency of `libpipewire-0.3-dev`. What is missing is the matching `-doc` packages. ## Plan ### Add the documentation packages to `[bootstrap.packages]` Edit the tracked `mise.toml` only. Do not touch `mise.local.toml`: it is untracked, carries the header `# Managed by omp-deck — edited in Settings → Workspaces. Local edits are overwritten.`, and is regenerated from a setting outside this repository. Append a new commented block at the end of `[bootstrap.packages]` (the table currently ends with `"apt:libmagicenum-dev" = "latest"`), matching the file's existing style of a short comment line above each group: ```toml # API documentation for the libraries above "apt:wireplumber-doc" = "latest" "apt:libglib2.0-doc" = "latest" "apt:pipewire-doc" = "latest" "apt:librtmidi-doc" = "latest" "apt:libasound2-doc" = "latest" ``` Use these package names verbatim. All five exist in Debian trixie at versions matching the declared `-dev` packages: `wireplumber-doc` 0.5.8-2, `libglib2.0-doc` 2.84.4-3~deb13u5, `pipewire-doc` 1.4.2-1, `librtmidi-doc` 6.0.0-2, `libasound2-doc` 1.2.14-1+deb13u1. `"latest"` matches the version value every existing entry in the table uses. Keep all existing entries, including every `-dev` entry, unchanged. Do not add `libspa-0.2-dev`: `libpipewire-0.3-dev` depends on it (`dep: libspa-0.2-dev (= 1.4.2-1)`), so it is already pulled in. Nothing else changes: no README section, no CMake change, no new file. The ten existing package entries and the `[tools]`, `[env]` and `[bootstrap.apt.sources.trixie-backports]` tables are untouched. ## Verification From the repository root: ``` mise bootstrap status ``` The output must list all five new entries as `packages apt:<name> …` lines — for example `packages apt:wireplumber-doc missing` — alongside the pre-existing ones. Each line proves two things at once: the TOML still parses (a syntax error makes the command fail instead of listing anything), and mise recognises each new key as a package entry rather than silently dropping it. The `missing` / `installed` state itself is not part of the acceptance criterion; an environment that has not installed them yet still passes. Installing the packages is out of scope for this change, so no check asserts that files appear under `/usr/share/doc/`. ## Assumptions & contingencies - `mise bootstrap status` is expected to run without privileges and without network access, as a read-only report. If it instead fails for a reason unrelated to this edit (for example no apt lists available), fall back to proving the edit with `mise config get bootstrap.packages` and confirm the five keys appear in its output; do not attempt to install anything.

omp-deck added the

Agent

Planned

label

2026-11-13 10:53:48 +01:00