docs: add sphinx docs and gitlab pages

docs/source/config.rst

@@ -0,0 +1,129 @@
+#############
+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.
+
+
+Sections
+########
+
+A config file is split into sections like so:
+
+.. code-block:: 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:
+
+.. code:: toml
+
+    [profiles]
+    current = "graphical"
+
+    [profiles.default]
+    parent = ""
+    device = "oneplus-enchilada"
+    flavour = "phosh"
+    pkgs_include = [ "wget", "rsync", "nano", "tmux", "zsh", "pv", ]
+    pkgs_exclude = []
+    hostname = "kupferphone"
+    username = "prawn"
+    size_extra_mb = 800
+
+    [profiles.graphical]
+    parent = "default"
+    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.