Skip to content

Commit

Permalink
Started a re-write of the docs (#1967)
Browse files Browse the repository at this point in the history
* Started a re-write of the docs, using CSV for tables and re-organizing parameter definitions

* Added final config options in --config, some have external references which needs to be populated

* Forgot to escape a comma

* Clarified a note

* Added disk configuration and disk encryption docs

* Changed way of installing using source and python

* Added a 'list script' that lists available scripts. This could be converted to a argparse later. But this does the trick for now. And it's added to ease documentation and listing of available options.

* Added a 'Known issues' section, as well as renamed the issues tab

* Finished up the known issues section

* Added a section regarding --plugin

* Added plugin description, tweaked disk_config to the latest changes from #2221

* Added custom-commands docs, and improved some creds and known issue links
  • Loading branch information
Torxed authored Nov 21, 2023
1 parent e6344f9 commit cc806d9
Show file tree
Hide file tree
Showing 21 changed files with 795 additions and 471 deletions.
3 changes: 2 additions & 1 deletion archinstall/__init__.py
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
"""Arch Linux installer - guided, templates etc."""
import importlib
import os
import sys
import time
import traceback
from argparse import ArgumentParser, Namespace
Expand Down Expand Up @@ -58,7 +59,7 @@
# For support reasons, we'll log the disk layout pre installation to match against post-installation layout
debug(f"Disk states before installing: {disk.disk_layouts()}")

if os.getuid() != 0:
if 'sphinx' not in sys.modules and os.getuid() != 0:
print(_("Archinstall requires root privileges to run. See --help for more."))
exit(1)

Expand Down
10 changes: 10 additions & 0 deletions archinstall/scripts/list.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
import glob
import pathlib

print("The following are viable --script options:")

for script in [pathlib.Path(x) for x in glob.glob(f"{pathlib.Path(__file__).parent}/*.py")]:
if script.stem in ['__init__', 'list']:
continue

print(f" {script.stem}")
3 changes: 3 additions & 0 deletions docs/_static/style.css
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
.wy-nav-content {
max-width: none;
}
4 changes: 4 additions & 0 deletions docs/_templates/layout.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
{% extends "!layout.html" %}
{% block extrahead %}
<link href="{{ pathto("_static/style.css", True) }}" rel="stylesheet" type="text/css">
{% endblock %}
10 changes: 0 additions & 10 deletions docs/archinstall/Application.rst

This file was deleted.

16 changes: 0 additions & 16 deletions docs/archinstall/Profile.rst

This file was deleted.

117 changes: 0 additions & 117 deletions docs/archinstall/general.rst

This file was deleted.

57 changes: 57 additions & 0 deletions docs/archinstall/plugins.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
.. _archinstall.Plugins:

Python Plugins
==============

``archinstall`` supports plugins via two methods.

First method is directly via the ``--plugin`` parameter when running as a CLI tool. This will load a specific plugin locally or remotely via a path.

The second method is via Python's built in `plugin discovery`_ using `entry points`_ categorized as ``archinstall.plugin``.

``--plugin`` parameter
----------------------

The parameter has the benefit of being stored in the ``--conf`` state, meaning when re-running an installation — the plugin will automatically be loaded.
It's limitation is that it requires an initial path to be known and written and be cumbersome.

Plugin Discovery
----------------

This method allows for multiple plugins to be loaded with the drawback that they have to be installed beforehand on the system running ``archinstall``.
This mainly targets those who build their own ISO's and package specific setups for their needs.


What's supported?
-----------------

Currently the documentation for this is scarse. Until that is resolved, the best way to find supported features is to search the source code for `plugin.on_ <https://github.com/search?q=repo%3Aarchlinux%2Farchinstall+%22plugin.on_%22&type=code>`_ as this will give a clear indication of which calls are made to plugins.

How does it work?
-----------------

``archinstall`` plugins use a discovery-driven approach where plugins are queried for certain functions.
As an example, if a plugin has the following function:

.. code-block:: python
def on_pacstrap(*packages):
...
The function :code:`archinstall.Pacman().strap(["some packages"])` is hardcoded to iterate plugins and look for :code:`on_pacstrap` in the plugin.
If the function exists, :code:`.strap()` will call the plugin's function and replace the initial package list with the result from the plugin.

The best way to document these calls is currently undecided, as it's hard to document this behavior dynamically.

Writing your own?
-----------------

The simplest way currently is to look at a reference implementation or the community. Two of these are:

* `torxed/archinstall-aur <https://github.com/torxed/archinstall-aur>`_
* `phisch/archinstall-aur <https://github.com/phisch/archinstall-aur>`_

And search for `plugin.on_ <https://github.com/search?q=repo%3Aarchlinux%2Farchinstall+%22plugin.on_%22&type=code>`_ in the code base to find what ``archinstall`` will look for. PR's are welcome to widen the support for this.

.. _plugin discovery: https://packaging.python.org/en/latest/specifications/entry-points/
.. _entry points: https://docs.python.org/3/library/importlib.metadata.html#entry-points
24 changes: 24 additions & 0 deletions docs/cli_parameters/config/config_options.csv
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
Key,Value(s),Description,Required
additional-repositories,[ `multilib <https://wiki.archlinux.org/title/Official_repositories#multilib>`_!, `testing <https://wiki.archlinux.org/title/Official_repositories#Testing_repositories>`_ ],Enables one or more of the testing and multilib repositories before proceeding with installation,No
archinstall-language,`lang <https://github.com/archlinux/archinstall/blob/master/archinstall/locales/languages.json>`__,Sets the TUI language used *(make sure to use the ``lang`` value not the ``abbr``)*,No
audio_config,`pipewire <https://wiki.archlinux.org/title/PipeWire>`_!, `pulseaudio <https://wiki.archlinux.org/title/PulseAudio>`_,Audioserver to be installed,No
bootloader,`Systemd-boot <https://wiki.archlinux.org/title/Systemd-boot>`_!, `grub <https://wiki.archlinux.org/title/GRUB>`_,Bootloader to be installed *(grub being mandatory on BIOS machines)*,Yes
debug,``true``!, ``false``,Enables debug output,No
disk_config,*Read more under* :ref:`disk config`,Contains the desired disk setup to be used during installation,No
disk_encryption,*Read more about under* :ref:`disk encryption`,Parameters for disk encryption applied ontop of ``disk_config``,No
hostname,``str``,A string definining your machines hostname on the network *(defaults to ``archinstall``)*,No
kernels,[ `linux <https://wiki.archlinux.org/title/Kernel#Officially_supported_kernels>`_!, `linux-hardened <https://wiki.archlinux.org/title/Kernel#Officially_supported_kernels>`_!, `linux-lts <https://wiki.archlinux.org/title/Kernel#Officially_supported_kernels>`_!, `linux-rt <https://wiki.archlinux.org/title/Kernel#Officially_supported_kernels>`_!, `linux-rt-lts <https://wiki.archlinux.org/title/Kernel#Officially_supported_kernels>`_!, `linux-zen <https://wiki.archlinux.org/title/Kernel#Officially_supported_kernels>`_ ],Defines which kernels should be installed and setup in the boot loader options,Yes
custom-commands,*Read more under* :ref:`custom commands`,Custom commands that will be run post-install chrooted inside the installed system,No
locale_config,{kb_layout: `lang <https://wiki.archlinux.org/title/Linux_console/Keyboard_configuration>`__!, sys_enc: `Character encoding <https://wiki.archlinux.org/title/Locale>`_!, sys_lang: `locale <https://wiki.archlinux.org/title/Locale>`_},Defines the keyboard key map!, system encoding and system locale,No
mirror_config,{custom_mirrors: [ https://... ]!, mirror_regions: { "Worldwide": [ "https://geo.mirror.pkgbuild.com/$repo/os/$arch" ] } },Sets various mirrors *(defaults to ISO's ``/etc/pacman.d/mirrors`` if not defined)*,No
network_config,*`see options under Network Configuration`*,Sets which type of *(if any)* network configuration should be used,No
no_pkg_lookups,``true``!, ``false``,Disabled package checking against https://archlinux.org/packages/,No
ntp,``true``!, ``false``,enables or disables `NTP <https://wiki.archlinux.org/title/Network_Time_Protocol_daemon>`_ during installation,No
offline,``true``!, ``false``,enables or disables certain online checks such as mirror reachability etc,No
packages,[ <package1>!, <package2>!, ... ],A list of packages to install during installation,No
parallel downloads,0-∞,sets a given number of paralell downloads to be used by `pacman <https://wiki.archlinux.org/title/Pacman#Enabling_parallel_downloads>`_,No
profile_config,*`read more under the profiles section`*,Installs a given profile if defined,No
script,`guided <https://github.com/archlinux/archinstall/blob/master/archinstall/scripts/guided.py>`__! *(default)*!, `minimal <https://github.com/archlinux/archinstall/blob/master/archinstall/scripts/minimal.py>`__!, `only_hdd <https://github.com/archlinux/archinstall/blob/master/archinstall/scripts/only_hdd.py>`_!, `swiss <https://github.com/archlinux/archinstall/blob/master/archinstall/scripts/swiss.py>`_!, `unattended <https://github.com/archlinux/archinstall/blob/master/archinstall/scripts/unattended.py>`_,When used to autorun an installation!, this sets which script to autorun with,No
silent,``true``!, ``false``,disables or enables user questions using the TUI,No
swap,``true``!, ``false``,enables or disables swap,No
timezone,`timezone <https://wiki.archlinux.org/title/System_time#Time_zone>`_,sets a timezone for the installed system,No
22 changes: 22 additions & 0 deletions docs/cli_parameters/config/custom_commands.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
.. _custom commands:

Custom Commands
===============

| Custom commands is a configuration entry that allows for executing custom commands post-installation.
| The commands are executed with `arch-chroot <https://man.archlinux.org/man/extra/arch-install-scripts/arch-chroot.8.en>`_.
The option takes a list of arguments, an example is:

.. code-block:: json
{
"custom-commands": [
"hostname new-hostname"
]
}
| The following example will set a new hostname in the installed system.
| The example is just to illustrate that the command is not run in the ISO but inside the installed system after the base system is installed.
More examples can be found in the code repository under `examples/ <https://github.com/archlinux/archinstall/tree/e6344f93f7e476d05bbcd642f2ed91fdde545870/examples>`_
Loading

0 comments on commit cc806d9

Please sign in to comment.