parchlinux-mobile/kupferbootstrap
1
0
Fork 1
mirror of https://gitlab.com/kupfer/kupferbootstrap.git synced 2025-02-23 05:35:44 -05:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs: convert to markdown with rst2myst

Browse source
This commit is contained in:
InsanePrawn 2022-11-10 01:25:47 +01:00
parent a8e8ddc4b4
commit fbd06eded5
11 changed files with 192 additions and 204 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
docs/requirements.txt
View file

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

18
docs/source/cli.md Normal file
View file

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

17
docs/source/cli.rst
View file

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

8
docs/source/cmd.rst → docs/source/cmd.md
View file

@ -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
```

2
docs/source/conf.py
View file

@ -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'

121
docs/source/config.md Normal file
View file

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

134
docs/source/config.rst
View file

@ -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.

12
docs/source/index.md Normal file
View file

@ -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
```

16
docs/source/index.rst
View file

@ -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

32
docs/source/install.md Normal file
View file

@ -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`!

35
docs/source/install.rst
View file

@ -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``!