docs: convert to markdown with rst2myst

docs/source/config.md

@@ -0,0 +1,121 @@
+# Configuration
+
+Kupferbootstrap uses [toml](https://en.wikipedia.org/wiki/TOML) for its configuration file.
+
+The file can either be edited manually or managed via the {doc}`cli/config` subcommand.
+
+You can quickly generate a default config by running {code}`kupferbootstrap config init -N`.
+
+## File Location
+
+The configuration is stored in `~/.config/kupfer/kupferbootstrap.toml`, where `~` is your user's home folder.
+
+Kupferbootstrap needs to create a number of folders, e.g. to download `PKGBUILDs.git` and store binary packages.
+By default, all of those folders live inside `~/.cache/kupfer/`.
+
+See also the `[paths]` section in your config.
+
+## Sections
+
+A config file is split into sections like so:
+
+```toml
+[pkgbuilds]
+git_repo = "https://gitlab.com/kupfer/packages/pkgbuilds.git"
+git_branch = "dev"
+
+[pacman]
+parallel_downloads = 3
+```
+
+Here, we have two sections: `pkgbuilds` and `pacman`.
+
+## Flavours
+
+Flavours are preset collections of software and functionality to enable,
+i.e. desktop environments like [Gnome](https://en.wikipedia.org/wiki/GNOME)
+and [Phosh](https://en.wikipedia.org/wiki/Phosh).
+
+## Profiles
+
+The last section and currently the only one with subsections is the `profiles` section.
+
+A profile is the configuration of a specific device image. It specifies (amongst others):
+
+- the device model
+- the flavour (desktop environment)
+- the host- and user name
+- extra packages to install
+
+Using a profile's `parent` key,
+you can inherit settings from another profile.
+
+This allows you to easily keep a number of slight variations of the same target profile around
+without the need to constantly modify your Kupferbootstrap configuration file.
+
+You can easily create new profiles with
+[kupferbootstrap config profile init](../cli/config/#kupferbootstrap-config-profile-init).
+
+Here's an example:
+
+```toml
+[profiles]
+current = "graphical"
+
+[profiles.default]
+parent = ""
+device = "oneplus-enchilada"
+flavour = "barebone"
+pkgs_include = [ "wget", "rsync", "nano", "tmux", "zsh", "pv", ]
+pkgs_exclude = []
+hostname = "kupferphone"
+username = "prawn"
+size_extra_mb = 800
+
+[profiles.graphical]
+parent = "default"
+flavour = "phosh"
+pkgs_include = [ "firefox", "tilix", "gnome-tweaks" ]
+size_extra_mb = "+3000"
+
+[profiles.hades]
+parent = "graphical"
+flavour = "phosh"
+hostname = "hades"
+
+[profiles.recovery]
+parent = "default"
+flavour = "debug-shell"
+
+[profiles.beryllium]
+parent = "graphical"
+device = "xiaomi-beryllium-ebbg"
+flavour = "gnome"
+hostname = "pocof1"
+```
+
+The `current` key in the `profiles` section controlls which profile gets used by Kupferbootstrap by default.
+
+The first subsection (`profiles.default`) describes the `default` profile
+which gets created by [config init](../cli/config/#kupferbootstrap-config-init).
+
+Next, we have a `graphical` profile that defines a couple of graphical programs for all but the `recovery` profile,
+since that doesn't have a GUI.
+
+### `size_extra_mb`
+
+Note how `size_extra_mb` can either be a plain integer (`800`) or a string,
+optionally leading with a plus sign (`+3000`),
+which instructs Kupferbootstrap to add the value to the parent profile's `size_extra_mb`.
+
+### `pkgs_include` / `pkgs_exclude`
+
+Like `size_extra_mb`, `pkgs_include` will be merged with the parent profile's `pkgs_include`.
+
+To exclude unwanted packages from being inherited from a parent profile, use `pkgs_exclude` in the child profile.
+
+```{hint}
+`pkgs_exclude` has no influence on Pacman's dependency resolution.
+It only blocks packages during image build that would usually be explicitly installed
+due to being listed in a parent profile or the selected flavour.
+```