From 108e1062fb0fc3914e59d411c4030f03f2877189 Mon Sep 17 00:00:00 2001 From: Jiri Kortus Date: Mon, 7 Aug 2023 17:30:14 +0200 Subject: [PATCH] Add documentation for recipe elements - document all existing elements and how to use them - some smallish fixes to existing documentation - add autosectionlabel extension to Sphinx configuration to enable better crossreferences. - add config file for readthedocs.io. --- .readthedocs.yaml | 33 ++ doc/101.rst | 4 +- doc/conf.py | 4 + doc/index.rst | 1 + doc/recipe_elements/advanced_partitioning.rst | 548 ++++++++++++++++++ doc/recipe_elements/configuration.rst | 107 ++++ doc/recipe_elements/connect_to_redhat.rst | 314 ++++++++++ doc/recipe_elements/create_user.rst | 115 ++++ doc/recipe_elements/datetime.rst | 133 +++++ doc/recipe_elements/hub.rst | 126 ++++ doc/recipe_elements/index.rst | 190 ++++++ doc/recipe_elements/initial_setup.rst | 181 ++++++ doc/recipe_elements/installation_source.rst | 224 +++++++ doc/recipe_elements/keyboard.rst | 120 ++++ doc/recipe_elements/language.rst | 20 + doc/recipe_elements/oscap_addon.rst | 124 ++++ doc/recipe_elements/partitioning.rst | 121 ++++ doc/recipe_elements/root_password.rst | 55 ++ doc/recipe_elements/software_selection.rst | 25 + doc/recipe_elements/syspurpose.rst | 27 + doc/recipe_elements/welcome.rst | 42 ++ 21 files changed, 2512 insertions(+), 2 deletions(-) create mode 100644 .readthedocs.yaml create mode 100644 doc/recipe_elements/advanced_partitioning.rst create mode 100644 doc/recipe_elements/configuration.rst create mode 100644 doc/recipe_elements/connect_to_redhat.rst create mode 100644 doc/recipe_elements/create_user.rst create mode 100644 doc/recipe_elements/datetime.rst create mode 100644 doc/recipe_elements/hub.rst create mode 100644 doc/recipe_elements/index.rst create mode 100644 doc/recipe_elements/initial_setup.rst create mode 100644 doc/recipe_elements/installation_source.rst create mode 100644 doc/recipe_elements/keyboard.rst create mode 100644 doc/recipe_elements/language.rst create mode 100644 doc/recipe_elements/oscap_addon.rst create mode 100644 doc/recipe_elements/partitioning.rst create mode 100644 doc/recipe_elements/root_password.rst create mode 100644 doc/recipe_elements/software_selection.rst create mode 100644 doc/recipe_elements/syspurpose.rst create mode 100644 doc/recipe_elements/welcome.rst diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 00000000..a07b47cd --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,33 @@ +# Read the Docs configuration file for Sphinx projects +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 +# Set the OS, Python version and other tools you might need +build: + os: ubuntu-22.04 + tools: + python: "3.11" + # You can also specify other tool versions: + # nodejs: "20" + # rust: "1.70" + # golang: "1.20" + +# Build documentation in the "docs/" directory with Sphinx +sphinx: + configuration: doc/conf.py + # You can configure Sphinx to use a different builder, for instance use the dirhtml builder for simpler URLs + # builder: "dirhtml" + # Fail on all warnings to avoid broken references + # fail_on_warning: true + +# Optionally build your docs in additional formats such as PDF and ePub +formats: + - pdf +# - epub +# Optional but recommended, declare the Python requirements required +# to build your documentation +# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html +# python: +# install: +# - requirements: docs/requirements.txt diff --git a/doc/101.rst b/doc/101.rst index f33620a7..7afb1722 100644 --- a/doc/101.rst +++ b/doc/101.rst @@ -226,8 +226,8 @@ Examples For example, in case of :xml:`` on "unchecked" and "clickable" (not greyed-out) checkbox: - * `action` - clicking on the checkbox - * `desired state` - checkbox is "checked" +* `action` - clicking on the checkbox +* `desired state` - checkbox is "checked" In this case (action="enable"), checkbox that is already checked is not clicked on because it's already in `desired state`. Clicking on it would make diff --git a/doc/conf.py b/doc/conf.py index 7b369e06..70f4f933 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -33,6 +33,7 @@ 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.mathjax', + 'sphinx.ext.autosectionlabel' ] # Add any paths that contain templates here, relative to this directory. @@ -263,3 +264,6 @@ #texinfo_no_detailmenu = False sys.path.append("../") + +# Make sure the target is unique +autosectionlabel_prefix_document = True \ No newline at end of file diff --git a/doc/index.rst b/doc/index.rst index e3994dbc..303948b3 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -52,6 +52,7 @@ Contents decorators history debugging + recipe_elements/index Indices and tables diff --git a/doc/recipe_elements/advanced_partitioning.rst b/doc/recipe_elements/advanced_partitioning.rst new file mode 100644 index 00000000..874505cb --- /dev/null +++ b/doc/recipe_elements/advanced_partitioning.rst @@ -0,0 +1,548 @@ +============================ +Manual Partitioning subspoke +============================ + + +/installation/hub/partitioning/advanced/add +=========================================== +Handles *add* (*+*) button and resulting dialog to add a new partition/LV. + +Attributes: + +* ``dialog`` - ``accept`` or ``reject`` + +/installation/hub/partitioning/advanced/add/mountpoint +====================================================== +*Mount Point* input field for a newly added partition or LV. + +Attributes: + +* ``value`` +* ``checked`` - ``yes`` or ``no`` + +/installation/hub/partitioning/advanced/add/size +================================================ +Mount point for a newly added partition or LV in *Add a New Mount Point* dialog. + + +Attributes: + +* ``value`` + +/installation/hub/partitioning/advanced/autopart +================================================ +Desired capacity for a newly added partition or LV in *Add a New Mount Point* dialog. + +Attributes: + +* ``value`` + +/installation/hub/partitioning/advanced/details +=============================================== +Handles device details for a selected partition/LV (the right part of the spoke). + +/installation/hub/partitioning/advanced/details/device_type +=========================================================== +*Device Type* combo box. + +Attributes: + +* ``select`` - device type according to following schema: + * ``native`` - standard partition + * ``btrfs`` + * ``lvm`` + * ``raid`` + * ``lvm thinp`` + +/installation/hub/partitioning/advanced/details/devices +======================================================= +Handles devices selection for a selected partition/LV (*Device(s):*/*Modify...*) button +and resulting dialog. + +Attributes: + +* ``dialog`` - ``accept`` or ``reject`` + +/installation/hub/partitioning/advanced/details/devices/deselect +================================================================ +Deselects a device in *Configure Mount Point* dialog. + +Attributes: + +* ``device`` - device name or glob pattern + +/installation/hub/partitioning/advanced/details/devices/select +============================================================== +Selects a device in *Configure Mount Point* dialog. + +Attributes: + +* ``device`` - device name or glob pattern + +/installation/hub/partitioning/advanced/details/edit_volume_group +================================================================= +Handles *Modify...* button for Volume Group related to selected LV and +resulting *Configure Volume Group* dialog. + +Attributes: + +* ``dialog`` - ``accept`` or ``reject`` + +/installation/hub/partitioning/advanced/details/edit_volume_group/devices +========================================================================= +Handles selection of devices related to a particular VG in +*Configure Volume Group* dialog. **Currently not implemented.** + +/installation/hub/partitioning/advanced/details/edit_volume_group/encrypt +========================================================================= +*Encrypt* check box in *Configure Volume Group* dialog. + +Attributes: + +* ``value`` - ``yes`` or ``no`` + +/installation/hub/partitioning/advanced/details/edit_volume_group/luks_version +============================================================================== +*LUKS Version* combo box in in *Configure Volume Group* dialog. + +Attributes: + +* ``value`` + +/installation/hub/partitioning/advanced/details/edit_volume_group/name +====================================================================== +VG *name* in *Configure Volume Group* dialog. + +Attributes: + +* ``value`` + +/installation/hub/partitioning/advanced/details/edit_volume_group/raid +====================================================================== +*RAID Level* combo box in *Configure Volume Group* dialog. + +Attributes: + +* ``select`` - level of RAID + +/installation/hub/partitioning/advanced/details/edit_volume_group/size +====================================================================== +Size field value in *Configure Volume Group* dialog. + +Attributes: + +* ``value`` + +/installation/hub/partitioning/advanced/details/edit_volume_group/size_policy +============================================================================= +*Size policy* combo box in *Configure Volume Group* dialog. + +Attributes: + +* ``select`` - size policy type (``fixed``, ``maximum`` or ``auto``) + +/installation/hub/partitioning/advanced/details/encrypt +======================================================= +*Encrypt* check box in partition/LV details. + +Attributes: + +* ``action`` - ``enable`` or ``disable`` + +/installation/hub/partitioning/advanced/details/filesystem +========================================================== +*File System* combo box in partition/LV details. + +Attributes: + +* ``select`` - FS type + +/installation/hub/partitioning/advanced/details/label +===================================================== +*Label* input field in partition/LV details. + +Attributes: + +* ``value`` + +/installation/hub/partitioning/advanced/details/mountpoint +========================================================== +*Mount Point* input field in partition/LV details. + +Attributes: + +* ``value`` + +/installation/hub/partitioning/advanced/details/name +==================================================== +*Name* input field in partition/LV details. + +Attributes: + +* ``value`` + +/installation/hub/partitioning/advanced/details/new_volume_group +================================================================ +Creates a new volume group using *Volume Group* combo box → +*Create a new volume group...* + +Attributes: + +* ``value`` +* ``checked`` - ``yes`` or ``no`` + +/installation/hub/partitioning/advanced/details/new_volume_group/devices +======================================================================== +Functionally equivalent to `/installation/hub/partitioning/advanced/details/edit_volume_group/devices`_ + +/installation/hub/partitioning/advanced/details/new_volume_group/encrypt +======================================================================== +Functionally equivalent to `/installation/hub/partitioning/advanced/details/edit_volume_group/encrypt`_ + +/installation/hub/partitioning/advanced/details/new_volume_group/luks_version +============================================================================= +Functionally equivalent to `/installation/hub/partitioning/advanced/details/edit_volume_group/luks_version`_ + +/installation/hub/partitioning/advanced/details/new_volume_group/name +===================================================================== +Functionally equivalent to `/installation/hub/partitioning/advanced/details/edit_volume_group/name`_ + +/installation/hub/partitioning/advanced/details/new_volume_group/raid +===================================================================== +Functionally equivalent to `/installation/hub/partitioning/advanced/details/edit_volume_group/raid`_ + +/installation/hub/partitioning/advanced/details/new_volume_group/size +===================================================================== +Functionally equivalent to `/installation/hub/partitioning/advanced/details/edit_volume_group/size`_ + +/installation/hub/partitioning/advanced/details/new_volume_group/size_policy +============================================================================ +Functionally equivalent to `/installation/hub/partitioning/advanced/details/edit_volume_group/size_policy`_ + +/installation/hub/partitioning/advanced/details/raid_type +========================================================= +*RAID Level* combo box in partition/LV details. + +Attributes: + +* ``select`` + +/installation/hub/partitioning/advanced/details/reformat +======================================================== +*Reformat* check box in partition/LV details. + +Attributes: + +* ``action`` - ``check`` or ``uncheck`` + +/installation/hub/partitioning/advanced/details/size +==================================================== +*Desired Capacity* input field in partition/LV details. + +Attributes: + +* ``value`` + +/installation/hub/partitioning/advanced/details/update +====================================================== +Clicks on *Update Settings* button in partition/LV details. + +/installation/hub/partitioning/advanced/done +============================================ +*Done* button + +/installation/hub/partitioning/advanced/encrypt_data +==================================================== +*Encrypt my data* check box on the left side of *Manual Partitioning* subspoke +present before automated creation of partitioning layout. + +Attributes: + +* ``action`` - ``enable`` or ``disable`` + +/installation/hub/partitioning/advanced/luks_dialog +=================================================== +Equivalent to :ref:`recipe_elements/partitioning:/installation/hub/partitioning/luks_dialog` +(including child elements). + +.. + /installation/hub/partitioning/advanced/luks_dialog/cancel + ========================================================== + Cancels the *Disk Encryption Passphrase* dialog. + + /installation/hub/partitioning/advanced/luks_dialog/confirm_password + ==================================================================== + *Confirm:* password field in *Disk Encryption Passphrase* dialog. + + Attributes: + + * ``value`` + + /installation/hub/partitioning/advanced/luks_dialog/keyboard + ============================================================ + Switches keyboard layout to a required one in *Disk Encryption Passphrase* dialog. + + Attributes: + + * ``layout`` + + /installation/hub/partitioning/advanced/luks_dialog/password + ============================================================ + *Passphrase* field in *Disk Encryption Passphrase* dialog. + + Attributes: + + * ``value`` + + /installation/hub/partitioning/advanced/luks_dialog/save + ======================================================== + Confirms the *Disk Encryption Passphrase* dialog (clicks on *Save Passphrase* button). + +/installation/hub/partitioning/advanced/remove +============================================== +Handles *remove* (*-*) button and the resulting confirmation dialog. + +Attributes: + +* ``dialog`` - ``accept`` or ``reject`` + +/installation/hub/partitioning/advanced/remove/also_related +=========================================================== +Handles *Delete all file systems which are only used by Red Hat Enterprise Linux X.Y +for * check box. + +Attributes: + +* ``value`` - ``yes`` or ``no`` + +/installation/hub/partitioning/advanced/rescan +============================================== +Handles *Reload storage configuration from disk* (rescan) button and related dialog. + +Attributes: + +* ``dialog`` - ``accept`` or ``reject`` + +/installation/hub/partitioning/advanced/rescan/push_rescan +========================================================== +Clicks on *Rescan Disks* button in *Rescan Disks* dialog. + +/installation/hub/partitioning/advanced/schema +============================================== +Handles partitioning schema (*New mount points will use the following +partitioning scheme:*) combo box. + +Attributes: + +* ``value`` - device type according to following schema: + * ``native`` - standard partition + * ``btrfs`` + * ``lvm`` + * ``raid`` + * ``lvm thinp`` + +/installation/hub/partitioning/advanced/select +============================================== +Shortcut to select and handle a set of available partitions/LVs based +on specified criteria. + +Attributes: + +* ``device`` - device name (e. g. `/dev/vda`) or glob pattern +* ``mountpoint`` - mount point path (or glob pattern) + +/installation/hub/partitioning/advanced/select/details +====================================================== +Configures details for selected partition(s)/LV(s) in the same way as +`/installation/hub/partitioning/advanced/details`_, including child elements. + +.. + It's likely not necessary to repeat the already mentioned paths/elements: + + /installation/hub/partitioning/advanced/select/details/device_type + ================================================================== + Equivalent to `/installation/hub/partitioning/advanced/details/device_type`_. + + /installation/hub/partitioning/advanced/select/details/devices + ============================================================== + Equivalent to `/installation/hub/partitioning/advanced/details/devices`_. + + /installation/hub/partitioning/advanced/select/details/devices/deselect + ======================================================================= + Equivalent to `/installation/hub/partitioning/advanced/details/devices/deselect`_. + + /installation/hub/partitioning/advanced/select/details/devices/select + ===================================================================== + Equivalent to `/installation/hub/partitioning/advanced/details/devices/select`_. + + /installation/hub/partitioning/advanced/select/details/edit_volume_group + ======================================================================== + Equivalent to `/installation/hub/partitioning/advanced/details/edit_volume_group`_. + + /installation/hub/partitioning/advanced/select/details/edit_volume_group/devices + ================================================================================ + Equivalent to `/installation/hub/partitioning/advanced/details/edit_volume_group/devices`_. + + /installation/hub/partitioning/advanced/select/details/edit_volume_group/encrypt + ================================================================================ + Equivalent to `/installation/hub/partitioning/advanced/details/edit_volume_group/encrypt`_. + + /installation/hub/partitioning/advanced/select/details/edit_volume_group/luks_version + ===================================================================================== + Equivalent to `/installation/hub/partitioning/advanced/details/edit_volume_group/luks_version`_. + + /installation/hub/partitioning/advanced/select/details/edit_volume_group/name + ============================================================================= + Equivalent to `/installation/hub/partitioning/advanced/details/edit_volume_group/name`_. + + /installation/hub/partitioning/advanced/select/details/edit_volume_group/raid + ============================================================================= + Equivalent to `/installation/hub/partitioning/advanced/details/edit_volume_group/raid`_. + + /installation/hub/partitioning/advanced/select/details/edit_volume_group/size + ============================================================================= + Equivalent to `/installation/hub/partitioning/advanced/details/edit_volume_group/size`_. + + /installation/hub/partitioning/advanced/select/details/edit_volume_group/size_policy + ==================================================================================== + Equivalent to `/installation/hub/partitioning/advanced/details/edit_volume_group/size_policy`_. + + /installation/hub/partitioning/advanced/select/details/encrypt + ============================================================== + Equivalent to `/installation/hub/partitioning/advanced/details/encrypt`_. + + /installation/hub/partitioning/advanced/select/details/filesystem + ================================================================= + Equivalent to `/installation/hub/partitioning/advanced/details/filesystem`_. + + /installation/hub/partitioning/advanced/select/details/label + ============================================================ + Equivalent to `/installation/hub/partitioning/advanced/details/label`_. + + /installation/hub/partitioning/advanced/select/details/mountpoint + ================================================================= + Equivalent to `/installation/hub/partitioning/advanced/details/mountpoint`_. + + /installation/hub/partitioning/advanced/select/details/name + =========================================================== + Equivalent to `/installation/hub/partitioning/advanced/details/name`_. + + /installation/hub/partitioning/advanced/select/details/new_volume_group + ======================================================================= + Equivalent to `/installation/hub/partitioning/advanced/details/new_volume_group`_. + + /installation/hub/partitioning/advanced/select/details/new_volume_group/devices + =============================================================================== + + + Attributes: + + * ``value`` + * ``checked`` - ``yes`` or ``no`` + + /installation/hub/partitioning/advanced/select/details/new_volume_group/encrypt + =============================================================================== + + + Attributes: + + * ``value`` + * ``checked`` - ``yes`` or ``no`` + + /installation/hub/partitioning/advanced/select/details/new_volume_group/luks_version + ==================================================================================== + + + Attributes: + + * ``value`` + * ``checked`` - ``yes`` or ``no`` + + /installation/hub/partitioning/advanced/select/details/new_volume_group/name + ============================================================================ + + + Attributes: + + * ``value`` + * ``checked`` - ``yes`` or ``no`` + + /installation/hub/partitioning/advanced/select/details/new_volume_group/raid + ============================================================================ + + + Attributes: + + * ``value`` + * ``checked`` - ``yes`` or ``no`` + + /installation/hub/partitioning/advanced/select/details/new_volume_group/size + ============================================================================ + + + Attributes: + + * ``value`` + * ``checked`` - ``yes`` or ``no`` + + /installation/hub/partitioning/advanced/select/details/new_volume_group/size_policy + =================================================================================== + + + Attributes: + + * ``value`` + * ``checked`` - ``yes`` or ``no`` + + /installation/hub/partitioning/advanced/select/details/raid_type + ================================================================ + + + Attributes: + + * ``value`` + * ``checked`` - ``yes`` or ``no`` + + /installation/hub/partitioning/advanced/select/details/reformat + =============================================================== + + + Attributes: + + * ``value`` + * ``checked`` - ``yes`` or ``no`` + + /installation/hub/partitioning/advanced/select/details/size + =========================================================== + + + Attributes: + + * ``value`` + * ``checked`` - ``yes`` or ``no`` + + /installation/hub/partitioning/advanced/select/details/update + ============================================================= + + + Attributes: + + * ``value`` + * ``checked`` - ``yes`` or ``no`` + +/installation/hub/partitioning/advanced/select/remove +===================================================== +Equivalent to `/installation/hub/partitioning/advanced/remove`_. + + +/installation/hub/partitioning/advanced/select/remove/also_related +================================================================== +Equivalent to `/installation/hub/partitioning/advanced/remove/also_related`_. + +/installation/hub/partitioning/advanced/summary +=============================================== +Handles *Summary of Changes* dialog. + +Attributes: + +* ``dialog`` - ``accept`` or ``reject`` diff --git a/doc/recipe_elements/configuration.rst b/doc/recipe_elements/configuration.rst new file mode 100644 index 00000000..c15e0ed3 --- /dev/null +++ b/doc/recipe_elements/configuration.rst @@ -0,0 +1,107 @@ +======================================== +Configuration/Installation process spoke +======================================== + +/installation/configuration +=========================== +Used for *configuration* spoke that appears during installation process and displays EULA +notice and Reboot button when installation is complete. + +.. note:: + This element originally provided options to create a user and set root password. + The elements for user/root configuration are internally equivalent to + :ref:`recipe_elements/hub:/installation/hub/create_user` and + :ref:`recipe_elements/hub:/installation/hub/root_password`. + +/installation/configuration/eula_notice +======================================= +Checks presence of warning bar on the bottom of the screen containing a proper message +about EULA which appears when the installation is complete. It has only a check implemented +(no handler), thus has to be used with ``policy=just_check``. + +/installation/configuration/finish_configuration +================================================ +Handles button used for finishing configuration during installation process (RHEL-7 only). + +/installation/configuration/reboot +================================== +Clicks *Reboot* button after installation is complete. + +/installation/configuration/root +================================ +A shortcut element usable only within the ``ez:`` namespace, functionally equivalent to +:ref:`recipe_elements/hub:/installation/hub/root`. + +/installation/configuration/root_password +========================================= +Functionally equivalent to :ref:`recipe_elements/hub:/installation/hub/root_password`. + +/installation/configuration/wait_until_complete +=============================================== +A special element not used to directly handle any Anaconda's function, but to wait +until for the installation process to finish. It is a necessary part before +clicking on the Reboot button as the button is inactive during installation. + +/installation/configuration/create_user/advanced +================================================ +Equivalent to :ref:`recipe_elements/create_user:/installation/hub/create_user/advanced`. + +/installation/configuration/create_user/advanced/cancel +======================================================= +Equivalent to :ref:`recipe_elements/create_user:/installation/hub/create_user/advanced/cancel`. + +/installation/configuration/create_user/advanced/gid +==================================================== +Equivalent to :ref:`recipe_elements/create_user:/installation/hub/create_user/advanced/gid`. + +/installation/configuration/create_user/advanced/groups +======================================================= +Equivalent to :ref:`recipe_elements/create_user:/installation/hub/create_user/advanced/groups`. + +/installation/configuration/create_user/advanced/home +===================================================== +Equivalent to :ref:`recipe_elements/create_user:/installation/hub/create_user/advanced/home`. + +/installation/configuration/create_user/advanced/manual_gid +=========================================================== +Equivalent to :ref:`recipe_elements/create_user:/installation/hub/create_user/advanced/manual_gid`. + +/installation/configuration/create_user/advanced/manual_uid +=========================================================== +Equivalent to :ref:`recipe_elements/create_user:/installation/hub/create_user/advanced/manual_uid`. + +/installation/configuration/create_user/advanced/save +===================================================== +Equivalent to :ref:`recipe_elements/create_user:/installation/hub/create_user/advanced/save`. + +/installation/configuration/create_user/advanced/uid +==================================================== +Equivalent to :ref:`recipe_elements/create_user:/installation/hub/create_user/advanced/uid`. + +/installation/configuration/create_user/confirm_password +======================================================== +Equivalent to :ref:`recipe_elements/create_user:/installation/hub/create_user/confirm_password`. + +/installation/configuration/create_user/done +============================================ +Equivalent to :ref:`recipe_elements/create_user:/installation/hub/create_user/done`. + +/installation/configuration/create_user/full_name +================================================= +Equivalent to :ref:`recipe_elements/create_user:/installation/hub/create_user/full_name`. + +/installation/configuration/create_user/is_admin +================================================ +Equivalent to :ref:`recipe_elements/create_user:/installation/hub/create_user/is_admin`. + +/installation/configuration/create_user/password +================================================ +Equivalent to :ref:`recipe_elements/create_user:/installation/hub/create_user/password`. + +/installation/configuration/create_user/require_password +======================================================== +Equivalent to :ref:`recipe_elements/create_user:/installation/hub/create_user/require_password`. + +/installation/configuration/create_user/username +================================================ +Equivalent to :ref:`recipe_elements/create_user:/installation/hub/create_user/username`. \ No newline at end of file diff --git a/doc/recipe_elements/connect_to_redhat.rst b/doc/recipe_elements/connect_to_redhat.rst new file mode 100644 index 00000000..22df883c --- /dev/null +++ b/doc/recipe_elements/connect_to_redhat.rst @@ -0,0 +1,314 @@ +======================== +Connect to Red Hat spoke +======================== + +/installation/hub/connect_to_redhat/account_organization +======================================================== +Combo box that appears for user in multiple organizations. + +Attributes: + +* ``value`` + +/installation/hub/connect_to_redhat/activation_key +================================================== +Input field - *Activation Key*. + +Attributes: + +* ``value`` + +/installation/hub/connect_to_redhat/authentication +================================================== +*Authentication* radio button. + +Attributes: + +* ``type`` - ``account`` or ``activation key`` + +/installation/hub/connect_to_redhat/insights +============================================ +*Connect to Red Hat Insights* check box. + +Attributes: + +* ``checked`` - ``yes`` or ``no`` + +/installation/hub/connect_to_redhat/options +=========================================== +Connection *Options* (HTTP proxy, custom server URL and base URL). + +/installation/hub/connect_to_redhat/options/custom_base_url +=========================================================== +*Custom base URL* input field. + +Attributes: + +* ``value`` + +/installation/hub/connect_to_redhat/options/custom_server_url +============================================================= +*Custom server URL* input field. + +Attributes: + +* ``value`` + +/installation/hub/connect_to_redhat/options/http_proxy +====================================================== +*Use HTTP proxy* checkbox (and related proxy settings handled +in child elements - see below). + +Attributes: + +* ``used`` - ``yes`` = enabled, anything else = disabled + +/installation/hub/connect_to_redhat/options/http_proxy/location +=============================================================== +HTTP proxy *Location* input field. + +Attributes: + +* ``value`` + +/installation/hub/connect_to_redhat/options/http_proxy/password +=============================================================== +HTTP proxy *Password* input field. + +Attributes: + +* ``value`` + +/installation/hub/connect_to_redhat/options/http_proxy/username +=============================================================== +HTTP proxy *User name* input field. + +Attributes: + +* ``value`` + +/installation/hub/connect_to_redhat/options/satellite_url +========================================================= +*Satellite URL* input field. + +Attributes: + +* ``value`` + +/installation/hub/connect_to_redhat/options/use_custom_base_url +=============================================================== +*Custom base URL* check box. + +Attributes: + +* ``checked`` - ``yes`` or ``no`` + +/installation/hub/connect_to_redhat/options/use_custom_server_url +================================================================= +*Custom server URL* check box. + +Attributes: + +* ``checked`` - ``yes`` or ``no`` + +/installation/hub/connect_to_redhat/options/use_satellite_url +============================================================= +*Satellite URL* check box. + +Attributes: + +* ``checked`` - ``yes`` or ``no`` + +/installation/hub/connect_to_redhat/organization +================================================ +*Organization* input field. + +Attributes: + +* ``value`` + +/installation/hub/connect_to_redhat/password +============================================ +*Organization* input field. + +Attributes: + +* ``value`` + +/installation/hub/connect_to_redhat/register +============================================ +*Register* button. + +/installation/hub/connect_to_redhat/registration +================================================ +Information about registration in registered state. + +/installation/hub/connect_to_redhat/registration/account_organization +===================================================================== +Registered account organization. + +Attributes: + +* ``value`` + +/installation/hub/connect_to_redhat/registration/insights +========================================================= +Insights status in registered state. + +Attributes: + +* ``used`` - ``yes`` or ``no`` + +/installation/hub/connect_to_redhat/registration/method +======================================================= +Registration method in registered state. + +Attributes: + +* ``account`` +* ``organization`` + +/installation/hub/connect_to_redhat/registration/subscriptions +============================================================== +Attached subscriptions in registered state. + +Attributes: + +* ``amount`` - amount of expected subscriptions; ``-1`` means that the amount + won't be checked, just the related label for 0/1/n subscriptions +* ``minAmount`` - minimal expected amount of subscriptions +* ``maxAmount`` - maximal expected amount of subscriptions + +/installation/hub/connect_to_redhat/registration/subscriptions/subscription +=========================================================================== +Name of subscription present in registered state. + +Attributes: + +* ``name`` - name or *fnmatchcase* expression for expected subscription + +/installation/hub/connect_to_redhat/registration/subscriptions/subscription/contract +==================================================================================== +Subscription contract in registered state. + +Attributes: + +* ``value`` + +/installation/hub/connect_to_redhat/registration/subscriptions/subscription/end_date +==================================================================================== +Subscription end date in registered state. + +Attributes: + +* ``value`` + +/installation/hub/connect_to_redhat/registration/subscriptions/subscription/entitlements_consumed +================================================================================================= +Consumed entitlements in registered state. + +Attributes: + +* ``value`` + +/installation/hub/connect_to_redhat/registration/subscriptions/subscription/service_level +========================================================================================= +Subscription service level in registered state. + +Attributes: + +* ``value`` + +/installation/hub/connect_to_redhat/registration/subscriptions/subscription/sku +=============================================================================== +Subscription SKU in registered state. + +Attributes: + +* ``value`` + +/installation/hub/connect_to_redhat/registration/subscriptions/subscription/start_date +====================================================================================== +Subscription start date in registered state. + +Attributes: + +* ``value`` + +/installation/hub/connect_to_redhat/registration/system_purpose +=============================================================== +System purpose in registered state, has no attributes. + +/installation/hub/connect_to_redhat/registration/system_purpose/role +==================================================================== +System purpose role in registered state. + +Attributes: + +* ``value`` + +/installation/hub/connect_to_redhat/registration/system_purpose/sla +=================================================================== +System purpose SLA in registered state. + +Attributes: + +* ``value`` + +/installation/hub/connect_to_redhat/registration/system_purpose/usage +===================================================================== +System purpose usage in registered state. + +Attributes: + +* ``value`` + +/installation/hub/connect_to_redhat/system_purpose +================================================== +*Set System Purpose* check box. + +Attributes: + +* ``set`` - ``yes`` or ``no`` + +/installation/hub/connect_to_redhat/system_purpose/role +======================================================= +System purpose *Role* combo box. + +Attributes: + +* ``value`` + +/installation/hub/connect_to_redhat/system_purpose/sla +====================================================== +System purpose *SLA* combo box. + +Attributes: + +* ``value`` + +/installation/hub/connect_to_redhat/system_purpose/usage +======================================================== +System purpose *Usage* combo box. + +Attributes: + +* ``value`` + +/installation/hub/connect_to_redhat/unregister +============================================== +*Unregister* button. + +/installation/hub/connect_to_redhat/username +============================================ +*User name* input field. + +Attributes: + +* ``value`` + +/installation/hub/connect_to_redhat/wait_until_registered +========================================================= +Element with a special meaning, blocking processing of further elements +until the registration process has completed, to ensure it took place +completely (successfully or unsuccessfully). diff --git a/doc/recipe_elements/create_user.rst b/doc/recipe_elements/create_user.rst new file mode 100644 index 00000000..1bcb886a --- /dev/null +++ b/doc/recipe_elements/create_user.rst @@ -0,0 +1,115 @@ +====================== +User Creation spoke +====================== + +/installation/hub/create_user/advanced +====================================== +Handles *Advanced User Configuration* dialog in *User Creation* spoke. + +/installation/hub/create_user/advanced/cancel +============================================= +Clicks on *Cancel* button. + +/installation/hub/create_user/advanced/gid +========================================== +*Specify a group ID manually* field. + +Attributes: + +* ``value`` + +/installation/hub/create_user/advanced/groups +============================================= +*Add user to the following groups* input field. + +Attributes: + +* ``value`` + +/installation/hub/create_user/advanced/home +=========================================== +*Home directory* input field. + +Attributes: + +* ``value`` + +/installation/hub/create_user/advanced/manual_gid +================================================= +*Specify a group ID manually* check box. + +Attributes: + +* ``set`` - ``yes`` or ``no`` + +/installation/hub/create_user/advanced/manual_uid +================================================= +*Specify a user ID manually* check box. + +Attributes: + +* ``set`` - ``yes`` or ``no`` + +/installation/hub/create_user/advanced/save +=========================================== +*Save Changes* button. + +/installation/hub/create_user/advanced/uid +========================================== +*Specify a user ID manually* field. + +Attributes: + +* ``value`` + +/installation/hub/create_user/confirm_password +============================================== +*Confirm password* input field. + +Attributes: + +* ``value`` + +/installation/hub/create_user/done +================================== +*Done* button. + +/installation/hub/create_user/full_name +======================================= +*Full name* input field. + +Attributes: + +* ``value`` + +/installation/hub/create_user/is_admin +====================================== +*Make this user administrator* check box. + +Attributes: + +* ``checked`` - ``yes`` or ``no`` + +/installation/hub/create_user/password +====================================== +*Password* input field. + +Attributes: + +* ``value`` + +/installation/hub/create_user/require_password +============================================== +*Require a password to use this account* check box. + +Attributes: + +* ``checked`` - ``yes`` or ``no`` + +/installation/hub/create_user/username +====================================== +*Confirm password* input field. + +Attributes: + +* ``value`` diff --git a/doc/recipe_elements/datetime.rst b/doc/recipe_elements/datetime.rst new file mode 100644 index 00000000..dda774c8 --- /dev/null +++ b/doc/recipe_elements/datetime.rst @@ -0,0 +1,133 @@ +================= +Time & Date spoke +================= + +/installation/hub/datetime/city +=============================== +*City* combo box. + +Attributes: + +* ``value`` + +/installation/hub/datetime/date +=============================== +Date represented by the day/month/year combo boxes. + +/installation/hub/datetime/date/day +=================================== +*Day* combo box. + +Attributes: + +* ``value`` + +/installation/hub/datetime/date/month +===================================== +*Month* combo box. + +Attributes: + +* ``value`` + +/installation/hub/datetime/date/year +==================================== +*Year* combo box. + + +Attributes: + +* ``value`` + +/installation/hub/datetime/ntp +============================== +*Network time* toggle button. + +Attributes: + +* ``action`` - ``enable`` or ``disable`` + +/installation/hub/datetime/ntp_settings +======================================= +Handles NTP settings dialog, accessed by the 'gears' NTP settings button. + +Attributes: + +* ``dialog`` - ``accept`` (confirms the settings), ``dialog`` (cancels the dialog) + +/installation/hub/datetime/ntp_settings/add +=========================================== +Add an NTP server to the list. + +Attributes: + +* ``hostname`` - server hostname to add + +/installation/hub/datetime/ntp_settings/disable +=============================================== +Disable an NTP server from the list. + +Attributes: + +* ``hostname`` - server hostname to disable + +/installation/hub/datetime/ntp_settings/enable +============================================== +Enable an NTP server from the list. + +Attributes: + +* ``hostname`` - server hostname to enable + +/installation/hub/datetime/ntp_settings/rename +============================================== +Rename an existing server from the list. + +Attributes: + +* ``old`` - (old) server hostname to rename +* ``new`` - new server hostname + +/installation/hub/datetime/region +================================= +*Region* combo box. + +Attributes: + +* ``value`` + +/installation/hub/datetime/time +=============================== +Time-related configuration. + +/installation/hub/datetime/time/ampm +==================================== +Set AM/PM. + +Attributes: + +* ``value`` + +/installation/hub/datetime/time/format +====================================== +Time format (24-hour or AM/PM) radio buttons. + +Attributes: + +* ``value`` - ``24`` for 24hour format or ``12`` for 12 (AM/PM) format + +/installation/hub/datetime/time/hours +===================================== +Hours value. + +Attributes: + +* ``value`` + +/installation/hub/datetime/time/minutes +======================================= +Minutes value. + +Attributes: + +* ``value`` diff --git a/doc/recipe_elements/hub.rst b/doc/recipe_elements/hub.rst new file mode 100644 index 00000000..4f6aeb22 --- /dev/null +++ b/doc/recipe_elements/hub.rst @@ -0,0 +1,126 @@ +============================== +Installation Hub (main screen) +============================== + +/installation/hub +================= +Handles main Anaconda hub (main screen with buttons for configuration of various areas - *spokes*), takes no attributes. + +/installation/hub/autopart +========================== +Shortcut element encompassing the following steps necessary to complete automatic partitioning: + +* Enter *Installation Destination* spoke, +* select all available standard and specialized disks, +* opt to reclaim additional space, +* remove all available partitions in the reclaim dialog, +* confirm the configuration. + +/installation/hub/begin_installation +==================================== +Clicks on *Begin installation* button. + +/installation/hub/connect_to_redhat +=================================== +Handles :doc:`Connect to Red Hat ` spoke. + +/installation/hub/create_user +============================= +Handles :doc:`User Creation ` spoke. + +/installation/hub/datetime +========================== +Handles :doc:`Time & Date ` spoke. + +/installation/hub/installation_source +===================================== +Handles :doc:`Installation Source ` spoke. + +/installation/hub/kdump +======================= +Handles *KDUMP* spoke. Only **entering/exiting** the spoke is implemented at this point, +i. e. there are no subelements of ``/installation/hub/kdump``. + +/installation/hub/keyboard +========================== +Handles :doc:`Keyboard ` spoke. + +/installation/hub/language_spoke +================================ +Handles :doc:`Language Support ` spoke. + +/installation/hub/luks_dialog +============================= +Equivalent to :ref:`recipe_elements/advanced_partitioning:/installation/hub/partitioning/advanced/luks_dialog`, +including child elements. +It can be used in this place with kickstart installations using +``--encrypted`` without ``--passphrase``). + +.. + /installation/hub/luks_dialog/cancel + ==================================== + Equivalent to `/installation/hub/partitioning/advanced/luks_dialog/cancel`_ + + /installation/hub/luks_dialog/confirm_password + ============================================== + Equivalent to `/installation/hub/partitioning/advanced/luks_dialog/confirm_password`_ + + /installation/hub/luks_dialog/keyboard + ====================================== + Equivalent to `/installation/hub/partitioning/advanced/luks_dialog/keyboard`_ + + /installation/hub/luks_dialog/password + ====================================== + Equivalent to `/installation/hub/partitioning/advanced/luks_dialog/password`_ + + /installation/hub/luks_dialog/save + ================================== + Equivalent to `/installation/hub/partitioning/advanced/luks_dialog/save`_ + +/installation/hub/oscap_addon +============================= +Handles `Security Profile ` spoke. + +Attributes: + +* ``fail_type`` - failure type shown on the spoke selector (button), depending + on the reason (``not_ready``, ``misconfiguration_detected``, ``warnings_appeared`` or + ``content_fetch_load_error``), used to distinguish the specific reason where necessary. +* ``expected_message`` - expected status message on the spoke selector (button) + +/installation/hub/partitioning +============================== +Handles :doc:`Installation Destination ` spoke. + +/installation/hub/root +====================== +Shortcut element usable only within ``ez:`` :ref:`namespace ` +to potentially make the recipe simpler by implicitly creating an `/installation/hub/root_password`_ +element after :ref:`preprocessing `. + +It also creates necessary subelements to arrange for automatic filling in of password +and confirmation password based on ``password`` attribute value and successfully exiting +the spoke by clicking on Done button twice, using ``may_fail`` policy. + +Attributes: + +* ``password`` + +/installation/hub/root_password +=============================== +Handles :doc:`Root Password ` spoke. + +/installation/hub/software_selection +==================================== +Handles :doc:`Software Selection ` spoke. + +Attributes: + +* ``save-selection`` - save information about software selection (environment + and addons) into ``/root/anabot-packageset.txt`` in the installed system - + ``yes`` or ``no`` (default) + +/installation/hub/syspurpose +============================ +Handles :doc:`System Purpose ` spoke. + diff --git a/doc/recipe_elements/index.rst b/doc/recipe_elements/index.rst new file mode 100644 index 00000000..dc68157c --- /dev/null +++ b/doc/recipe_elements/index.rst @@ -0,0 +1,190 @@ +############### +Recipe elements +############### + +******** +Overview +******** + +The Anabot recipe is an XML file consisting of specific elements. +Here's an overview of supported elements, represented as a path in the +tree-like structure of the file for a better readability. + +There are two main areas (applications) covered by Anabot - Anaconda and Initial Setup. + +As Anabot uses *handlers* (functions typically performing an actual action in the GUI) +and *checks* (functions checking that the action took place in an expected way); they +return results based on whether the action/check was successful. + +The expected outcome can be defined by ``policy`` attribute of any element in the recipe +(when description of any element below states that it takes no attributes, it means arguments +*specific* for the particular element) and it can contain the following values: + +* ``should_pass`` (implicit value) - the element's handler should be executed and + it is expected that check result should be successful +* ``should_fail`` - similar, but the check is expected to fail +* ``just_check`` - don't execute the handler (don't perform any action), only check + the expected resulting state (e. g. an input field contains expected text) +* ``just_check_fail`` - don't perform any action, only check that the expected result + is **not** present + +A small subset of elements (e. g. :doc:`/installation/hub/oscap_addon `) +also supports ``fail_type`` attribute, which can be used for a finer handling of the +specific failure reason. + +.. note:: + + The elements description below describe available attributes and their meanings and values. + If a meaning and/or allowed values of an attribute aren't mentioned explicitly, they are + considered obvious from the context (i. e. ``value`` attribute for a text input field). + + In a similar way, some attributes take binary values by nature (e. g. enable/disable, + accept/reject), but technically, on implementation level, one of the values is + exactly specified (e. g. ``enable``) and the complementary one can be + represented by any, unspecified value (e. g. ``disable``, ``disabled`` or even ``foobar``). + In such cases the following descriptions can specify a specific value even on places + where an arbitrary (complementary, unspecified) one could be used for the sake of + clarity. It is strongly advised to only use those specified values so as to + make things easy to understand and consistent, instead of some arbitrary ones, + despite their functional equivalence. + +******** +Anaconda +******** + +The *ez* namespace +================== +Anabot's preprocessor supports omitting parts of the recipe (elements or attributes) +while creating the necessary attributes itself, thus making the recipe creation +somewhat easier and more readable. + +This can be achieved by using the ``ez`` prefix within the supported elements +(after first defining the namespace). + +For instance, a recipe containing just + +.. code-block:: xml + + + + + + + +will expand into a functionally complete minimal recipe containing the explicitly defined +parts (````), with the rest generated automatically by preprocessor: + +.. code-block:: xml + + + + + + + + + + + +