Address asciidoctor-dita-vale issues for rex (#4379)

* Add abstract role and create basic abstracts

* Apply various small fixes to address asciidoctor-dita-vale

* Remove links in additional resources for transport modes

If users have trouble navigating through an assembly, the solution is
not to start throwing links at them; the solution is to fix up the
assembly's structure

* Split modules into web UI + CLI

* Rewrite setting up job templates to resolve asciidoctor-dita-vale issues

---------

Co-authored-by: Maximilian Kolb <[email protected]>

Author: aneta-petrova

guides/common/assembly_configuring-and-setting-up-remote-jobs.adoc

@@ -18,15 +18,21 @@ ifdef::katello,orcharhino,satellite[]
 include::modules/proc_configuring-a-host-to-use-the-pull-client.adoc[leveloffset=+1]
 endif::[]
 
-include::modules/proc_creating-a-job-template.adoc[leveloffset=+1]
+include::modules/proc_creating-a-job-template-by-using-web-ui.adoc[leveloffset=+1]
+
+include::modules/proc_creating-a-job-template-by-using-cli.adoc[leveloffset=+1]
 
 include::modules/proc_importing-an-ansible-playbook-by-name.adoc[leveloffset=+1]
 
 include::modules/proc_importing-all-available-ansible-playbooks.adoc[leveloffset=+1]
 
-include::modules/proc_configuring-the-fallback-to-any-smartproxy-remote-execution-setting-in-project.adoc[leveloffset=+1]
+include::modules/proc_configuring-the-fallback-to-any-smartproxy-remote-execution-setting-by-using-web-ui.adoc[leveloffset=+1]
+
+include::modules/proc_configuring-the-fallback-to-any-smartproxy-remote-execution-setting-by-using-cli.adoc[leveloffset=+1]
 
-include::modules/proc_configuring-the-global-smartproxy-remote-execution-setting-in-project.adoc[leveloffset=+1]
+include::modules/proc_configuring-the-global-smartproxy-remote-execution-setting-by-using-web-ui.adoc[leveloffset=+1]
+
+include::modules/proc_configuring-the-global-smartproxy-remote-execution-setting-by-using-cli.adoc[leveloffset=+1]
 
 include::modules/proc_setting-an-alternative-directory-for-remote-execution-jobs-in-push-mode.adoc[leveloffset=+1]
 
@@ -67,9 +73,11 @@ include::modules/proc_configuring-a-keytab-for-kerberos-ticket-granting-tickets.
 
 include::modules/proc_configuring-kerberos-authentication-for-remote-execution.adoc[leveloffset=+1]
 
-include::modules/proc_setting-up-job-templates.adoc[leveloffset=+1]
+include::modules/proc_customizing-job-templates.adoc[leveloffset=+1]
+
+include::modules/proc_executing-a-remote-job-by-using-web-ui.adoc[leveloffset=+1]
 
-include::modules/proc_executing-a-remote-job.adoc[leveloffset=+1]
+include::modules/proc_executing-a-remote-job-by-using-cli.adoc[leveloffset=+1]
 
 include::modules/ref_advanced-settings-in-the-job-wizard.adoc[leveloffset=+1]
 

guides/common/modules/con_configuring-and-setting-up-remote-jobs.adoc

@@ -3,5 +3,6 @@
 [id="Configuring_and_Setting_Up_Remote_Jobs_{context}"]
 = Configuring and setting up remote jobs
 
+[role="_abstract"]
 {ProjectName} supports remote execution of commands on hosts.
 Using remote execution, you can perform various tasks on multiple hosts simultaneously.

guides/common/modules/con_permissions-for-remote-execution.adoc

@@ -3,7 +3,9 @@
 [id="permissions-for-remote-execution_{context}"]
 = Permissions for remote execution
 
+[role="_abstract"]
 You can control which roles can run which jobs within your infrastructure, including which hosts they can target.
+
 The remote execution feature provides two built-in roles:
 
 * *Remote Execution Manager*: Can access all remote execution features and functionality.

guides/common/modules/con_remote-execution-in-project.adoc

@@ -3,6 +3,7 @@
 [id="Remote-Execution-in-{ProjectNameID}_{context}"]
 = Remote execution in {ProjectName}
 
+[role="_abstract"]
 With remote execution, you can run jobs on hosts from {SmartProxies} by using shell scripts or Ansible roles and playbooks.
 
 Use remote execution for the following benefits in {Project}:
@@ -31,13 +32,10 @@ endif::[]
 
 By default, {Project} includes several job templates for shell scripts and Ansible.
 ifdef::configuring-ansible,managing-hosts[]
-For more information, see xref:setting-up-job-templates_{context}[].
+For more information, see xref:customizing-job-templates[].
 endif::[]
+ifeval::["{context}" == "planning"]
 
 .Additional resources
-ifdef::configuring-ansible,managing-hosts[]
-* See xref:executing-a-remote-job_{context}[].
-endif::[]
-ifeval::["{context}" == "planning"]
-* See {ManagingConfigurationsAnsibleDocURL}Configuring_and_Setting_Up_Remote_Jobs_ansible[Configuring and setting up remote jobs] in _{ManagingConfigurationsAnsibleDocTitle}_.
+* {ManagingConfigurationsAnsibleDocURL}Configuring_and_Setting_Up_Remote_Jobs_ansible[Configuring and setting up remote jobs in _{ManagingConfigurationsAnsibleDocTitle}_]
 endif::[]

guides/common/modules/con_remote-execution-workflow.adoc

@@ -3,11 +3,12 @@
 [id="remote-execution-workflow_{context}"]
 = Remote execution workflow
 
+[role="_abstract"]
+When you run a remote job on hosts, for every host, {Project} performs a series of actions to find a remote execution {SmartProxy} to use.
+
 For custom Ansible roles that you create, or roles that you download, you must install the package containing the roles on your {SmartProxyServer}.
 Before you can use Ansible roles, you must import the roles into {Project} from the {SmartProxy} where they are installed.
 
-When you run a remote job on hosts, for every host, {Project} performs the following actions to find a remote execution {SmartProxy} to use.
-
 ifeval::["{context}" == "managing-hosts"]
 {Project} searches only for {SmartProxies} that have the remote execution feature enabled.
 endif::[]

guides/common/modules/con_transport-modes-for-remote-execution.adoc

@@ -3,7 +3,10 @@
 [id="transport-modes-for-remote-execution_{context}"]
 = Transport modes for remote execution
 
+[role="_abstract"]
 You can configure your {Project} to use two different modes of transport for remote job execution.
+
+The following transport modes are available for remote execution.
 You can configure single {SmartProxy} to use either one mode or the other but not both.
 
 Push-based transport::
@@ -33,21 +36,3 @@ If your {SmartProxy} already uses the `pull-mqtt` mode and you want to switch ba
 # {foreman-installer} --foreman-proxy-plugin-remote-execution-script-mode ssh
 ----
 ====
-
-.Additional resources
-* To enable pull mode on {SmartProxyServer}, see {InstallingSmartProxyDocURL}configuring-pull-based-transport-for-remote-execution_{smart-proxy-context}[Configuring pull-based transport for remote execution] in _{InstallingSmartProxyDocTitle}_.
-ifdef::katello,orcharhino,satellite[]
-* To enable pull mode on a registered host, continue with xref:Configuring_a_Host_to_Use_the_Pull_Client_{context}[].
-endif::[]
-ifdef::managing-hosts[]
-* To enable pull mode on a new host, continue with the following:
-
-** xref:Creating_a_Host_{context}[]
-** xref:Registering_Hosts_by_Using_Global_Registration_{context}[]
-endif::[]
-ifndef::managing-hosts[]
-* To enable pull mode on a new host, continue with the following in _{ManagingHostsDocTitle}_:
-
-** {ManagingHostsDocURL}Creating_a_Host_managing-hosts[Creating a Host]
-** {ManagingHostsDocURL}Registering_Hosts_by_Using_Global_Registration_managing-hosts[Registering hosts by using global registration]
-endif::[]

guides/common/modules/con_using-extended-cron-lines.adoc

@@ -3,7 +3,9 @@
 [id="using-extended-cron-lines_{context}"]
 = Using extended cron lines
 
+[role="_abstract"]
 When scheduling a cron job with remote execution, you can use an extended cron line to specify the cadence of the job.
+
 The standard cron line contains five fields that specify minute, hour, day of the month, month, and day of the week.
 For example, `0 5 * * *` stands for every day at 5 AM.
 ifdef::foreman-deb,foreman-el,katello[]

guides/common/modules/proc_adding-a-passphrase-to-ssh-key-used-for-remote-execution.adoc

@@ -3,6 +3,7 @@
 [id="adding-a-passphrase-to-ssh-key-used-for-remote-execution_{context}"]
 = Adding a passphrase to SSH key used for remote execution
 
+[role="_abstract"]
 By default, {SmartProxy} uses a non-passphrase protected SSH key to execute remote jobs on hosts.
 You can protect the SSH key with a passphrase by following this procedure.
 

guides/common/modules/proc_altering-the-privilege-elevation-method.adoc

@@ -3,6 +3,7 @@
 [id="altering-the-privilege-elevation-method_{context}"]
 = Altering the privilege elevation method
 
+[role="_abstract"]
 By default, push-based remote execution uses `sudo` to switch from the SSH user to the effective user that executes the script on your host.
 In some situations, you might require to use another method, such as `su` or `dzdo`.
 You can globally configure an alternative method in your {Project} settings.

guides/common/modules/proc_applying-remote-scap-resources-in-a-disconnected-environment.adoc

@@ -62,5 +62,5 @@ For example, use the `Run Command - Script Default` job template and enter the f
 # curl -o /root/_security-data-oval-com.redhat.rhsa-RHEL8.xml.bz2_ http://_{foreman-example-com}_/pulp/content/_My_Organization_Label_/Library/custom/_My_Product_Label_/_My_Repo_Label_/_security-data-oval-com.redhat.rhsa-RHEL8.xml.bz2_
 ----
 +
-For more information about running remote jobs, see {ManagingHostsDocURL}executing-a-remote-job_managing-hosts[Executing a Remote Job] in _{ManagingHostsDocTitle}_.
+For more information about running remote jobs, see {ManagingHostsDocURL}Configuring_and_Setting_Up_Remote_Jobs_managing-hosts[Configuring and setting up remote jobs] in _{ManagingHostsDocTitle}_.
 . Continue with deploying your compliance policy.