docs: move usage guides to usage/, add quickstart and porting

docs/source/index.md

@@ -6,7 +6,6 @@ a tool to build and flash packages and images for the [Kupfer](https://gitlab.co
 ## Documentation pages
 
 ```{toctree}
-install
+usage/index
-config
 cli
 ```

docs/source/usage/config.md

@@ -2,7 +2,7 @@
 
 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.
+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`.
 
@@ -54,7 +54,7 @@ This allows you to easily keep a number of slight variations of the same target
 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).
+[kupferbootstrap config profile init](/cli/config/#kupferbootstrap-config-profile-init).
 
 Here's an example:
 
@@ -97,7 +97,7 @@ 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).
+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.

docs/source/usage/faq.md

@@ -0,0 +1,39 @@
+# FAQ
+
+
+```{contents} Table of Contents
+:class: this-will-duplicate-information-and-it-is-still-useful-here
+:depth: 3
+```
+
+
+## Which devices are currently supported?
+
+Currently very few!  
+See [the `devices` repo](https://gitlab.com/kupfer/packages/pkgbuilds/-/tree/dev/device). We use the same codenames as [postmarketOS](https://wiki.postmarketos.org/wiki/Devices) (although we prefix them with the SoC)
+
+
+## How to port a new device or package?
+
+See [Porting](../porting)
+
+## How to build a specific package
+
+See also: The full [`kupferbootstrap packages build` docs](/cli/packages#kupferbootstrap-packages-build)
+
+### Example
+
+For rebuilding `kupfer-config` and `crossdirect`, defaulting to your device's architecture
+
+```sh
+kupferbootstrap packages build [--force] [--arch $target_arch] kupfer-config crossdirect
+```
+
+
+### By package path
+You can also use the a path snippet (`$repo/$pkgbase`) to the PKGBUILD folder as seen inside your pkgbuilds.git:
+
+```sh
+kupferbootstrap packages build [--force] main/kupfer-config cross/crossdirect
+```
+

docs/source/usage/index.md

@@ -0,0 +1,9 @@
+# Usage
+
+```{toctree}
+quickstart
+faq
+install
+config
+porting
+```

docs/source/usage/porting.md

@@ -0,0 +1,94 @@
+# Porting
+## Porting devices
+
+### Homework
+Before you can get started porting a device, you'll need to do some research:
+
+1. Familiarize yourself with git basics.
+1. Familiarize yourself with Arch Linux packaging, i.e. `PKGBUILD`s and `makepkg`
+1. Familiarize yourself with the postmarketOS port of the device.
+   ```{warning}
+    If there is no postmarketOS port yet, you'll probably need to get deep into kernel development.  
+    We suggest [starting with a port to pmOS](https://wiki.postmarketos.org/wiki/Porting_to_a_new_device) then, especially if you're not familiar with the process already.
+    ```
+
+### Porting
+1. Navigate to your pkgbuilds checkout
+1. Follow the [general package porting guidelines](#porting-packages) to create a device-, kernel- and probably also a firmware-package for the device and SoC. Usually this roughly means porting the postmarketOS APKBUILDs to our PKGBUILD scheme.  
+   You can get inspiration by comparing existing Kupfer ports (e.g. one of the SDM845 devices) to the [postmarketOS packages](https://gitlab.com/postmarketOS/pmaports/-/tree/master/device) for that device.
+   Usually you should start out by copying and then customizing the Kupfer packages for a device that's as similar to yours as possible, i.e. uses the same or a related SoC, if something like that is already available in Kupfer.
+   ```{hint} Package Repos:
+   Device packages belong into `device/`, kernels into `linux/` and firmware into `firmware/`.
+   ```
+1. When submitting your MR, please include some information:
+    - what you have found to be working, broken, and not tested (and why)
+    - any necessary instructions for testing
+    - whether you'd be willing to maintain the device long-term (test kernel upgrades, submit device package updates, etc.)
+
+
+### Gotchas
+
+Please be aware of these gotchas:
+- As of now, Kupfer only really supports platforms using Android's `aboot` bootloader, i.e. ex-Android phones. In order to support other boot modes (e.g. uboot on the Librem5 and Pine devices), we'll need to port and switch to postmarketOS's [boot-deploy](https://gitlab.com/postmarketOS/boot-deploy) first and add support for EFI setups to Kupferbootstrap.
+
+
+## Porting packages
+
+### Homework
+Before you can get started, you'll need to do some research:
+
+1. Familiarize yourself with git basics.
+1. Familiarize yourself with Arch Linux packaging, i.e. `PKGBUILD`s and `makepkg`
+
+### Development
+
+```{warning}
+Throughout the process, use git to version your changes.  
+- Don't procrastinate using git or committing until you're "done" or "have got something working", you'll regret it.  
+- Don't worry about a "clean" git history while you're developing; we can squash it up later.
+- \[Force-]Push your changes regularly, just like committing. Don't wait for perfection.
+```
+1. Create a new git branch for your package locally.
+   ```{hint}
+   It might be a good ideaa to get into the habit of prefixing branch names with \[a part of] your username and a slash like so:  
+   `myNickname/myFeatureNme`  
+   This makes it easier to work in the same remote repo with multiple people.
+   ```
+1. 
+   ```{note}
+   The pkgbuilds git repo contains multiple package repositories, represented by folders at the top level (`main`, `cross`, `phosh`, etc.).  
+   ```
+   Try to choose a sensible package repo for your new packages and create new folders for each `pkgbase` inside the repo folder.
+1. Navigate into the folder of the new package and create a new `PKGBUILD`; fill it with life!
+1. **`_mode`**: Add the build mode at the top of the PKGBUILD.
+   ```{hint}
+   If you're unsure what to pick, go with `_mode=host`. It'll use `crossdirect` to get speeds close to proper cross-compiling.
+   ```
+   This determines whether it's built using a foreign-arch chroot (`_mode=host`) executed with qemu-user, or using real cross-compilation (`_mode=cross`) from a host-architecture chroot, but the package's build tooling has to specifically support the latter, so it's mostly useful for kernels and uncompiled packages.
+1. **`_nodeps`**: (Optional) If your package doesn't require its listed dependencies to build
+   (usually because you're packaging a meta-package or only configs or scripts)
+   you can add `_nodeps=true` as the next line after the `_mode=` line to speed up packaging.
+   `makedeps` are still installed anyway.
+1. Test building it with `kupferbootstrap packages build $pkgbname`
+1. For any files and git repos downloaded by your PKGBUILD,
+   add them to a new `.gitignore` file in the same directory as your `PKGBUILD`.  
+   ```{hint}
+   Don't forget to `git add` the new `.gitignore` file!
+   ```
+1. Run `kupferbootstrap packages check` to make sure the formatting for your PKGBUILDs is okay.
+   ```{warning}
+   This is **not** optional. MRs with failing CI will **not** be merged.
+   ```
+
+### Pushing
+1. Fork the Kupfer pkgbuilds repo on Gitlab using the Fork button
+1. Add your fork's **SSH** URI to your local git repo as a **new remote**: `git remote add fork git@gitlab...`
+1. `git push -u fork $branchname` it
+
+### Submitting the MR
+When you're ready, open a Merge Request on the Kupfer pkgbuilds repo.
+
+```{hint}
+Prefix the MR title with `Draft: ` to indicate a Work In Progress state.
+```
+

docs/source/usage/quickstart.md

@@ -0,0 +1,9 @@
+# Quickstart
+
+1. [Install](../install) Kupferbootstrap
+1. [Configure](../config) it: `kuperbootstrap config init`
+1. [Update your PKGBUILDs + SRCINFO cache](/cli/packages#kupferbootstrap-packages-update): `kupferbootstrap packages update`
+1. [Build an image](/cli/image#kupferbootstrap-image-build): `kupferbootstrap image build`
+1. [Flash the image](/cli/image#kupferbootstrap-image-flash): `kupferbootstrap image flash abootimg && kupferbootstrap image flash full userdata`
+
+See also: [Frequently Asked Questions](../faq)