docs: convert to markdown with rst2myst

docs/requirements.txt

@@ -1,3 +1,4 @@
 sphinx-click
+myst-parser
 # furo sphinx theme
 furo

docs/source/cli.md

@@ -0,0 +1,18 @@
+# CLI Interface
+
+```{eval-rst}
+.. click:: main:cli
+   :nested: none
+   :prog: kupferbootstrap
+
+```
+
+## Commands
+
+% generated by cmd.rst
+
+```{toctree}
+:glob: true
+
+cli/*
+```

docs/source/cli.rst

@@ -1,17 +0,0 @@
-#############
-CLI Interface
-#############
-
-.. click:: main:cli
-   :nested: none
-   :prog: kupferbootstrap
-
-
-Commands
-========
-
-.. generated by cmd.rst
-.. toctree::
-    :glob:
-
-    cli/*

docs/source/cmd.md

@@ -1,8 +1,11 @@
-:orphan:
+---
-:nosearch:
+nosearch: true
+orphan: true
+---
 
 only used to trigger builds of the submodule docs!
 
+```{eval-rst}
 .. autosummary::
    :toctree: cli
    :template: command.rst
@@ -16,3 +19,4 @@ only used to trigger builds of the submodule docs!
     image
     net
     packages
+```

docs/source/conf.py

@@ -5,7 +5,9 @@ sys.path.insert(0, os.path.abspath('../..'))
 extensions = [
     'sphinx_click',
     'sphinx.ext.autosummary',  # Create neat summary tables
+    'myst_parser'
 ]
+myst_all_links_external = True
 templates_path = ['templates']
 project = 'Kupfer👢strap'
 html_title = 'Kupferbootstrap'

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.
+```

docs/source/config.rst

@@ -1,134 +0,0 @@
-#############
-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:
-
-.. 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 = "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.

docs/source/index.md

@@ -0,0 +1,12 @@
+# Kupferbootstrap Documentation
+
+This is the documentation for [Kupferbootstrap](https://gitlab.com/kupfer/kupferbootstrap),
+a tool to build and flash packages and images for the [Kupfer](https://gitlab.com/kupfer/) mobile Linux distro.
+
+## Documentation pages
+
+```{toctree}
+install
+config
+cli
+```

docs/source/index.rst

@@ -1,16 +0,0 @@
-#############################
-Kupferbootstrap Documentation
-#############################
-
-This is the documentation for `Kupferbootstrap <https://gitlab.com/kupfer/kupferbootstrap>`_,
-a tool to build and flash packages and images for the `Kupfer <https://gitlab.com/kupfer/>`_ mobile Linux distro.
-
-
-Documentation pages
-===================
-
-.. toctree::
-
-    install
-    config
-    cli

docs/source/install.md

@@ -0,0 +1,32 @@
+# Installation
+
+1. Install Python 3, Docker, and git.
+
+   On Arch: `pacman -S python docker git --needed --noconfirm`
+
+   ```{Hint}
+   After installing Docker you will have to add your user to the `docker` group:
+
+   `sudo usermod -aG docker "$(whoami)"`
+
+   Then restart your desktop session for the new group to take effect.
+   ```
+
+2. Pick which Kupferbootstrap branch to clone: usually either `main` or `dev`
+
+3. Clone the repository: `git clone -b INSERT_BRANCHNAME_HERE https://gitlab.com/kupfer/kupferbootstrap`
+
+4. Change into the folder: `cd kupferbootstrap`
+
+5. Install python dependencies: `pip3 install -r requirements.txt`
+
+   ```{Note}
+   Most of our python dependencies are available as distro packages on most distros,
+   sadly it's incomplete on Arch.
+
+   See `requirements.txt` for the list of required python packages.
+   ```
+
+6. Symlink `kupferbootstrap` into your `$PATH`: `sudo ln -s "$(pwd)/bin/kupferbootstrap" /usr/local/bin/`
+
+7. You should now be able to run `kupferbootstrap --help`!

docs/source/install.rst

@@ -1,35 +0,0 @@
-############
-Installation
-############
-
-
-#.
-  Install Python 3, Docker, and git.
-
-  On Arch: ``pacman -S python docker git --needed --noconfirm``
-
-  .. Hint::
-      After installing Docker you will have to add your user to the ``docker`` group:
-
-      ``sudo usermod -aG docker "$(whoami)"``
-
-      Then restart your desktop session for the new group to take effect.
-
-#. Pick which Kupferbootstrap branch to clone: usually either ``main`` or ``dev``
-
-#. Clone the repository: ``git clone -b INSERT_BRANCHNAME_HERE https://gitlab.com/kupfer/kupferbootstrap``
-
-#. Change into the folder: ``cd kupferbootstrap``
-
-#.
-  Install python dependencies: ``pip3 install -r requirements.txt``
-
-  .. Note::
-      Most of our python dependencies are available as distro packages on most distros,
-      sadly it's incomplete on Arch.
-
-      See ``requirements.txt`` for the list of required python packages.
-
-#. Symlink ``kupferbootstrap`` into your ``$PATH``: ``sudo ln -s "$(pwd)/bin/kupferbootstrap" /usr/local/bin/``
-
-#. You should now be able to run ``kupferbootstrap --help``!