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/README.md | 17 +++++ docs/archinstall/Installer.rst | 2 +- docs/examples/python.rst | 4 +- docs/help/discord.rst | 2 +- docs/help/issues.rst | 8 +-- docs/index.rst | 4 +- docs/installing/binary.rst | 4 +- docs/installing/guided.rst | 137 ++++++++++++++++++++++------------------- docs/installing/python.rst | 6 +- 9 files changed, 104 insertions(+), 80 deletions(-) create mode 100644 docs/README.md (limited to 'docs') diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..7ab47d26 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,17 @@ +## Dependencies + +In order to build the docs locally, you need to have the following installed: + +- [sphinx-doc](https://www.sphinx-doc.org/en/master/usage/installation.html) +- [sphinx-rdt-theme](https://pypi.org/project/sphinx-rtd-theme/) + +For example, you may install these dependencies using pip: +``` +pip install -U sphinx sphinx-rtd-theme +``` + +For other installation methods refer to the docs of the dependencies. + +## Build + +In `archinstall/docs`, run `make html` (or specify another target) to build locally. The build files will be in `archinstall/docs/_build`. Open `_build/html/index.html` with your browser to see your changes in action. \ No newline at end of file diff --git a/docs/archinstall/Installer.rst b/docs/archinstall/Installer.rst index 22d73116..d1bbaa7c 100644 --- a/docs/archinstall/Installer.rst +++ b/docs/archinstall/Installer.rst @@ -3,7 +3,7 @@ archinstall.Installer ===================== -The installer is the main class for accessing a installation-instance. +The installer is the main class for accessing an installation-instance. You can look at this class as the installation you have or will perform. Anything related to **inside** the installation, will be found in this class. diff --git a/docs/examples/python.rst b/docs/examples/python.rst index 342ec5c7..c3904863 100644 --- a/docs/examples/python.rst +++ b/docs/examples/python.rst @@ -6,7 +6,7 @@ Python module Archinstall supports running in `module mode `_. The way the library is invoked in module mode is limited to executing scripts under the **example** folder. -It's there for important to place any script or profile you wish to invoke in the examples folder prior to building and installing. +It's therefore important to place any script or profile you wish to invoke in the examples folder prior to building and installing. Pre-requisites -------------- @@ -56,4 +56,4 @@ This should now print all available drives on your system. .. note:: - This should work on any system, not just Arch Linux based ones. But note that other functions in the library relies heavily on Arch Linux based commands to execute the installation steps. Such as `arch-chroot`. + This should work on any system, not just Arch Linux based ones. But note that other functions in the library rely heavily on Arch Linux based commands to execute the installation steps. Such as `arch-chroot`. diff --git a/docs/help/discord.rst b/docs/help/discord.rst index 73727c35..4075bc54 100644 --- a/docs/help/discord.rst +++ b/docs/help/discord.rst @@ -3,7 +3,7 @@ Discord ======= -There's a discord channel which is frequented by some contributors `_. +There's a discord channel which is frequented by some `contributors `_. To join the server, head over to `https://discord.gg/cqXU88y `_'s server and join in. There's not many rules other than common sense and to treat others with respect. diff --git a/docs/help/issues.rst b/docs/help/issues.rst index d4f71b70..7e8d04c0 100644 --- a/docs/help/issues.rst +++ b/docs/help/issues.rst @@ -6,17 +6,17 @@ Issue tracker & bugs Issues and bugs should be reported over at `https://github.com/archlinux/archinstall/issues `_. General questions, enhancements and security issues can be reported over there too. -For quick issues or if you need help, head over the to the Discord server which has a help channel. +For quick issues or if you need help, head over to the Discord server which has a help channel. Submitting a help ticket ======================== | When submitting a help ticket, please include the :code:`/var/log/archinstall/install.log`. -| It can be found both on the live ISO but also in the installed filesystem if the base packages was strapped in. +| It can be found both on the live ISO but also in the installed filesystem if the base packages were strapped in. | There are additional worker files, these worker files contain individual command input and output. -| These worker files are located in :code:`~/.cache/archinstall/` and does not need to be submitted by default when submitting issues. +| These worker files are located in :code:`~/.cache/archinstall/` and do not need to be submitted by default when submitting issues. .. warning:: - Worker log-files *may* contain sensitive information such as **passwords** and **private information**. Never submit these logs without going through them manually making sure they're good for submission. Or submit parts of it that's relevant to the issue itself. + Worker log-files *may* contain sensitive information such as **passwords** and **private information**. Never submit these logs without going through them manually making sure they're good for submission. Or submit only parts of them which are relevant to the issue itself. diff --git a/docs/index.rst b/docs/index.rst index 0d80501b..c9a6aca4 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -2,7 +2,7 @@ python-archinstall Documentation ================================ | **python-archinstall** *(or, archinstall for short)* is a helper library to install Arch Linux and manage services, packages and other things. -| It comes packaged with different pre-configured installers, such as the `Guided installation`_ installer. +| It comes packaged with different pre-configured installers, such as the :ref:`guided_installation` installer. | | A demo can be viewed here: `https://www.youtube.com/watch?v=9Xt7X_Iqg6E `_ which uses the default guided installer. @@ -10,7 +10,7 @@ Some of the features of Archinstall are: * **No external dependencies or installation requirements.** Runs without any external requirements or installation processes. -* **Single threaded and context friendly.** The library always executed calls in sequential order to ensure installation-steps don't overlap or executes in the wrong order. It also supports *(and uses)* context wrappers to ensure things such as `sync` are called so data and configurations aren't lost. +* **Single threaded and context friendly.** The library always executes calls in sequential order to ensure installation-steps don't overlap or execute in the wrong order. It also supports *(and uses)* context wrappers to ensure things such as `sync` are called so data and configurations aren't lost. * **Supports standalone executable** The library can be compiled into a single executable and run on any system with or without Python. This is ideal for live mediums that don't want to ship Python as a big dependency. 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-70-g09d2