From c6b499cf47fac7a02714e590cf662a85db3095b1 Mon Sep 17 00:00:00 2001 From: remLse Date: Sat, 18 Dec 2021 19:01:40 +0100 Subject: Update documentation (#803) * Add guide for building docs locally * Update documentation - Fix typos - Fix some formatting - Fix broken links - Improve readability of json profile specification --- docs/installing/binary.rst | 4 +- docs/installing/guided.rst | 137 ++++++++++++++++++++++++--------------------- docs/installing/python.rst | 6 +- 3 files changed, 77 insertions(+), 70 deletions(-) (limited to 'docs/installing') diff --git a/docs/installing/binary.rst b/docs/installing/binary.rst index 504d6e3e..eeb9d79d 100644 --- a/docs/installing/binary.rst +++ b/docs/installing/binary.rst @@ -21,7 +21,7 @@ Archinstall is on the `official repositories `_ contains a binary `PKGBUILD `_ which can be either copied straight off the website. Or cloned using `git clone https://github.com/Torxed/archinstall`. +The `source `_ contains a binary `PKGBUILD `_ which can be either copied straight off the website or cloned using :code:`git clone https://github.com/Torxed/archinstall`. Once you've obtained the `PKGBUILD`, building it is pretty straight forward. @@ -29,7 +29,7 @@ Once you've obtained the `PKGBUILD`, building it is pretty straight forward. makepkg -s -Which should produce a `archinstall-X.x.z-1.pkg.tar.zst` that can be installed using: +Which should produce an `archinstall-X.x.z-1.pkg.tar.zst` which can be installed using: .. code-block:: console diff --git a/docs/installing/guided.rst b/docs/installing/guided.rst index 03225adb..19720a3f 100644 --- a/docs/installing/guided.rst +++ b/docs/installing/guided.rst @@ -1,7 +1,10 @@ +.. _guided_installation: +.. autofunction:: guided_installation + Guided installation =================== -This is the default scripted installation you'll encounter on the official Arch Linux Archinstall package as well as the unofficial ISO found on `https://archlinux.life `_. It will guide your through a very basic installation of Arch Linux. +This is the default scripted installation you'll encounter on the official Arch Linux Archinstall package as well as the unofficial ISO found on `https://archlinux.life `_. It will guide you through a very basic installation of Arch Linux. The installer has two pre-requisites: @@ -9,8 +12,8 @@ The installer has two pre-requisites: * An active internet connection prior to running archinstall .. warning:: - A basic understanding of how machines, ISO-files and command lines are needed. - Please read the official Arch Linux Wiki *(`https://wiki.archlinux.org/ `_ to learn more)* + A basic understanding of machines, ISO-files and command lines are needed. + Please read the official Arch Linux Wiki (`https://wiki.archlinux.org/ `_) to learn more .. note:: There are some limitations with the installer, such as that it will not configure WiFi during the installation procedure. And it will not perform a post-installation network configuration either. So you need to read up on `Arch Linux networking `_ to get that to work. @@ -37,7 +40,7 @@ And to run it, execute archinstall as a Python module: python -m archinstall --script guided | The ``--script guided`` argument is optional as it's the default behavior. -| But this will start the process of guiding you through a installation of a quite minimal Arch Linux experience. +| But this will start the process of guiding you through an installation of a quite minimal Arch Linux experience. Installing directly from a configuration file -------------------------------------- @@ -91,61 +94,66 @@ To run it, execute archinstall as a Python module: .. code-block:: sh python -m archinstall --config - -+----------------------+--------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------+-----------------------------------------------+ -| Key | Values/Description | Description | Required | -| | | | | -+======================+======================================================================================================================================+======================================================================================+===============================================+ -| audio | pipewire/pulseaudio | Audioserver to be installed | No | -+----------------------+--------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------+-----------------------------------------------+ -| bootloader | systemd-bootctl/grub-install | Bootloader to be installed | Yes | -+----------------------+--------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------+-----------------------------------------------+ -| custom-commands | [ , , ...] | Custom commands to be run post install | No | -+----------------------+--------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------+-----------------------------------------------+ -| !encryption-password | any | Password to encrypt disk, not encrypted if password not provided | No | -+----------------------+--------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------+-----------------------------------------------+ -| filesystem | ext4 / btrfs / fat32 etc. | Filesystem for root and home partitions | Yes | -+----------------------+--------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------+-----------------------------------------------+ -| gfx_driver | "VMware / VirtualBox (open-source)" or "Nvidia" or "Intel (open-source)" or "AMD / ATI (open-source)" or "All open-source (default)" | Graphics Drivers to install | No | -| | | | | -+----------------------+--------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------+-----------------------------------------------+ -| harddrive | { "path": } | Path of device to be used | Yes | -+----------------------+--------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------+-----------------------------------------------+ -| hostname | any | Hostname of machine after installation | Yes | -+----------------------+--------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------+-----------------------------------------------+ -| kernels | [ "kernel1", "kernel2"] | List of kernels to install eg: linux, linux-lts, linux-zen etc | Atleast 1 | -+----------------------+--------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------+-----------------------------------------------+ -| keyboard-language | 2 letter code for your keyboard language | eg: us, de etc | Yes | -+----------------------+--------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------+-----------------------------------------------+ -| mirror-region | {"": { "Mirror Name": True/False}, ..} | List of regions and mirrors to use | Yes | -+----------------------+--------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------+-----------------------------------------------+ -| nic | { NetworkManager: , nic: } | | Yes | -+----------------------+--------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------+-----------------------------------------------+ -| ntp | | Set to true to set-up ntp post install | No | -+----------------------+--------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------+-----------------------------------------------+ -| packages | [ "package1", "package2", ..] | List of packages to install post-installation | No | -+----------------------+--------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------+-----------------------------------------------+ -| profile | Name of the profile to install | Profiles are present in profiles/, use the name of a profile to install it | No | -+----------------------+--------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------+-----------------------------------------------+ -| !root-password | any | The root account password | No | -+----------------------+--------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------+-----------------------------------------------+ -| services | [ "service1", "service2", ..] | Services to enable post-installation | No | -+----------------------+--------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------+-----------------------------------------------+ -| sys-encoding | "utf-8" | Set to change system encoding post-install, ignored if --advanced flag is not passed | No | -+----------------------+--------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------+-----------------------------------------------+ -| sys-language | "en_US" | Set to change system language post-install, ignored if --advanced flag is not passed | No | -+----------------------+--------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------+-----------------------------------------------+ -| superusers | { "": { "!password": ""}, ..} | List of superuser credentials, see configuration for reference | Yes, if root account password is not provided | -+----------------------+--------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------+-----------------------------------------------+ -| timezone | Timezone to configure in installation | Timezone eg: UTC, Asia/Kolkata etc. | Yes | -+----------------------+--------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------+-----------------------------------------------+ -| users | { "": { "!password": ""}, ..} | List of regular user credentials, see configuration for reference | Yes, can be {} | -+----------------------+--------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------+-----------------------------------------------+ - + ++----------------------+-----------------------------------------------------+--------------------------------------------------------------------------------------+-----------------------------------------------+ +| Key | Values/Description | Description | Required | +| | | | | ++======================+=====================================================+======================================================================================+===============================================+ +| audio | pipewire/pulseaudio | Audioserver to be installed | No | ++----------------------+-----------------------------------------------------+--------------------------------------------------------------------------------------+-----------------------------------------------+ +| bootloader | systemd-bootctl/grub-install | Bootloader to be installed | Yes | ++----------------------+-----------------------------------------------------+--------------------------------------------------------------------------------------+-----------------------------------------------+ +| custom-commands | [ , , ...] | Custom commands to be run post install | No | ++----------------------+-----------------------------------------------------+--------------------------------------------------------------------------------------+-----------------------------------------------+ +| !encryption-password | any | Password to encrypt disk, not encrypted if password not provided | No | ++----------------------+-----------------------------------------------------+--------------------------------------------------------------------------------------+-----------------------------------------------+ +| filesystem | ext4 / btrfs / fat32 etc. | Filesystem for root and home partitions | Yes | ++----------------------+-----------------------------------------------------+--------------------------------------------------------------------------------------+-----------------------------------------------+ +| gfx_driver | - "VMware / VirtualBox (open-source)" | Graphics Drivers to install | No | +| | - "Nvidia" | | | +| | - "Intel (open-source)" | | | +| | - "AMD / ATI (open-source)" | | | +| | - "All open-source (default)" | | | ++----------------------+-----------------------------------------------------+--------------------------------------------------------------------------------------+-----------------------------------------------+ +| harddrive | { "path": } | Path of device to be used | Yes | ++----------------------+-----------------------------------------------------+--------------------------------------------------------------------------------------+-----------------------------------------------+ +| hostname | any | Hostname of machine after installation | Yes | ++----------------------+-----------------------------------------------------+--------------------------------------------------------------------------------------+-----------------------------------------------+ +| kernels | [ "kernel1", "kernel2"] | List of kernels to install eg: linux, linux-lts, linux-zen etc | Atleast 1 | ++----------------------+-----------------------------------------------------+--------------------------------------------------------------------------------------+-----------------------------------------------+ +| keyboard-language | 2 letter code for your keyboard language | eg: us, de etc | Yes | ++----------------------+-----------------------------------------------------+--------------------------------------------------------------------------------------+-----------------------------------------------+ +| mirror-region | {"": { "Mirror Name": True/False}, ..} | List of regions and mirrors to use | Yes | ++----------------------+-----------------------------------------------------+--------------------------------------------------------------------------------------+-----------------------------------------------+ +| nic | { NetworkManager: , nic: } | | Yes | ++----------------------+-----------------------------------------------------+--------------------------------------------------------------------------------------+-----------------------------------------------+ +| ntp | | Set to true to set-up ntp post install | No | ++----------------------+-----------------------------------------------------+--------------------------------------------------------------------------------------+-----------------------------------------------+ +| packages | [ "package1", "package2", ..] | List of packages to install post-installation | No | ++----------------------+-----------------------------------------------------+--------------------------------------------------------------------------------------+-----------------------------------------------+ +| profile | Name of the profile to install | Profiles are present in profiles/, use the name of a profile to install it | No | ++----------------------+-----------------------------------------------------+--------------------------------------------------------------------------------------+-----------------------------------------------+ +| !root-password | any | The root account password | No | ++----------------------+-----------------------------------------------------+--------------------------------------------------------------------------------------+-----------------------------------------------+ +| services | [ "service1", "service2", ..] | Services to enable post-installation | No | ++----------------------+-----------------------------------------------------+--------------------------------------------------------------------------------------+-----------------------------------------------+ +| sys-encoding | "utf-8" | Set to change system encoding post-install, ignored if --advanced flag is not passed | No | ++----------------------+-----------------------------------------------------+--------------------------------------------------------------------------------------+-----------------------------------------------+ +| sys-language | "en_US" | Set to change system language post-install, ignored if --advanced flag is not passed | No | ++----------------------+-----------------------------------------------------+--------------------------------------------------------------------------------------+-----------------------------------------------+ +| superusers | { "": { "!password": ""}, ..} | List of superuser credentials, see configuration for reference | Yes, if root account password is not provided | ++----------------------+-----------------------------------------------------+--------------------------------------------------------------------------------------+-----------------------------------------------+ +| timezone | Timezone to configure in installation | Timezone eg: UTC, Asia/Kolkata etc. | Yes | ++----------------------+-----------------------------------------------------+--------------------------------------------------------------------------------------+-----------------------------------------------+ +| users | { "": { "!password": ""}, ..} | List of regular user credentials, see configuration for reference | Yes, can be {} | ++----------------------+-----------------------------------------------------+--------------------------------------------------------------------------------------+-----------------------------------------------+ + +(To see which keys are required, scroll to the right in the above table.) + Description individual steps ============================ -Below is a description of each individual steps in order. +Below is a description of each individual step in order. keyboard languages ------------------ @@ -169,7 +177,7 @@ Default is :code:`auto detect best mirror` As an example: - * :code:`Sweden` *(with a capital :code:`S`)* will only use mirrors from Sweden. + * :code:`Sweden` *(with a capital* :code:`S`) will only use mirrors from Sweden. Selection of drive ------------------ @@ -250,27 +258,26 @@ Some additional packages can be installed if need be. This step allows you to li Network configuration --------------------- -| In this step is optional and allows for some basic configuration of your network. +| This step is optional and allows for some basic configuration of your network. | There are two main options and two sub-options, the two main ones are: * Copy existing network configuration from the ISO you're working on * Select **one** network interface to configure -| If copying existing configuration is chosen, no further configuration is needed. -| The installer will copy any wireless *(based on :code:`iwd`)* configurations and :code:`systemd-networkd` configuration set up by the user or the default system configuration. +| If copying the existing configuration is chosen, no further configuration is needed. +| The installer will copy any wireless *(based on* :code:`iwd`) configurations and :code:`systemd-networkd` configuration set up by the user or the default system configuration. -| If a interface was selected instead, a secondary option will be presented, allowing you to choose between two options: +| If an interface was selected instead, a secondary option will be presented, allowing you to choose between two options: * Automatic DHCP configuration of IP, DNS and Gateway - * Static IP configuration that further will ask some mandatory questions + * Static IP configuration that will ask some further mandatory questions Configuration verification -------------------------- -| Before the installer continues, and this is only valid for the **guided installation**. -| The chosen configuration will be printed on the screen and you have the option to verify it. +| Before the installer continues, and this is only valid for the **guided installation**, the chosen configuration will be printed on the screen and you have the option to verify it. -After which you can press :code:`Enter` can be pressed in order to start the formatting and installation process. +After which you can press :code:`Enter` in order to start the formatting and installation process. .. warning:: After a 5 second countdown, the selected drive will be permanently erased and all data will be lost. diff --git a/docs/installing/python.rst b/docs/installing/python.rst index 68365753..940d4e97 100644 --- a/docs/installing/python.rst +++ b/docs/installing/python.rst @@ -49,14 +49,14 @@ Which will allow you to start using the library. Manual installation ------------------- -You can either download the github repo as a zip archive. -Or you can clone it, we'll clone it here but both methods work the same. +You can either download the github repo as a zip archive, or you can clone it. +We'll clone it here but both methods work the same. .. code-block:: console git clone https://github.com/archlinux/archinstall -Either you can move the folder into your project and simply do +You can either move the folder into your project and simply do .. code-block:: python -- cgit v1.2.3-54-g00ecf