From 4f32e1995f2ccf6a69fd7b625a48f8a71887681d Mon Sep 17 00:00:00 2001 From: Kristal Dale Date: Tue, 16 Jul 2019 15:23:16 -0700 Subject: [PATCH] Maintenance Guides: Basic link clean up in advance of translation of content (#625) * Basic link clean up in advance of translation of content - Remove unused links - Updated links defined as named refs to use simple text e.g. name of linked content instead of narrative text - Minor edits to accomodate minor changes to name of ref links Signed-off-by: Kristal Dale * Update links according to feedback on PR. Signed-off-by: Kristal Dale * Update link according to feedback on PR. Signed-off-by: Kristal Dale --- .../maintenance/architect-lifecycle.rst | 15 +++++-- .../guides/maintenance/bulk-provision.rst | 8 ++-- .../guides/maintenance/cpu-performance.rst | 13 +++--- .../maintenance/developer-workstation.rst | 7 +-- .../guides/maintenance/enable-user-space.rst | 11 +++-- .../guides/maintenance/kernel-development.rst | 45 +++++++++---------- .../maintenance/kernel-modules-dkms.rst | 24 ++++------ .../guides/maintenance/kernel-modules.rst | 9 ++-- 8 files changed, 66 insertions(+), 66 deletions(-) diff --git a/source/clear-linux/guides/maintenance/architect-lifecycle.rst b/source/clear-linux/guides/maintenance/architect-lifecycle.rst index bf9e8787..f166e542 100644 --- a/source/clear-linux/guides/maintenance/architect-lifecycle.rst +++ b/source/clear-linux/guides/maintenance/architect-lifecycle.rst @@ -38,7 +38,8 @@ Description Coordinated infrastructure is deployed to automate the life-cycle of your |CL| derivative. We divide deployment of this infrastucture in two -parts: *Content Workflow*; and *Release Workflow*, shown in Figure 1. Distro Factory manages the *Release Workflow* while capturing the requirements for +parts: *Content Workflow*; and *Release Workflow*, shown in Figure 1. Distro +Factory manages the *Release Workflow* while capturing the requirements for maintaining a long-term release cadence. .. figure:: figures/architect-lifecycle-1.png @@ -51,7 +52,12 @@ Content workflow **************** The *Content Workflow* (Figure 1) orchestrates the processes used to manage -the creation of content for the distribution. This includes everything from detecting a new release in a custom software repository to generating RPM package files. The RPM files serve as intermediary artifacts that track software dependencies and provide file-level data consumed in a *Release Workflow*. The `Watcher Pipeline`_ checks |CL| and a content provider, such as Koji, to determine if a new release is necessary. +the creation of content for the distribution. This includes everything from +detecting a new release in a custom software repository to generating RPM +package files. The RPM files serve as intermediary artifacts that track software +dependencies and provide file-level data consumed in a *Release Workflow*. The +`Watcher Pipeline`_ checks |CL| and a content provider, such as Koji, to +determine if a new release is necessary. Release workflow **************** @@ -67,9 +73,10 @@ new releases. Implementation ************** -Distro factory implements the *Release workflow*. To get started on a full implementation, visit |CL| `Distro factory documentation`_. +Distro factory implements the *Release workflow*. To get started on a full +implementation, visit |CL| `Distro Factory`_ documentation. -.. _Distro factory documentation: https://github.com/clearlinux/clr-distro-factory/wiki#clear-linux-distro-factory +.. _Distro Factory: https://github.com/clearlinux/clr-distro-factory/wiki#clear-linux-distro-factory .. _Release Pipeline: https://github.com/clearlinux/clr-distro-factory/wiki/Release diff --git a/source/clear-linux/guides/maintenance/bulk-provision.rst b/source/clear-linux/guides/maintenance/bulk-provision.rst index 6b52e760..9d3affc2 100644 --- a/source/clear-linux/guides/maintenance/bulk-provision.rst +++ b/source/clear-linux/guides/maintenance/bulk-provision.rst @@ -41,7 +41,7 @@ Configuration ============= #. Install **ICIS** by following the getting started guide on the - `ICIS GitHub repository`_. + `ICIS`_ GitHub repository. #. Create an Ister installation file and save it to the :file:`static/ister` directory within the web hosting directory for @@ -116,7 +116,7 @@ Configuration location of the Ister configuration file. #. Write a cloud-init document to customize the instance of the installation - according to your requirements. The `cloud-init Read the Docs`_ provides a + according to your requirements. The `cloud-init`_ documentation provides a guide on how to write a cloud-init document. The guide covers the customization options provided by cloud-init after an installation. @@ -158,8 +158,8 @@ Configuration **Congratulations!** You have successfully performed a bulk provision of |CL|. -.. _ICIS GitHub repository: +.. _ICIS: https://github.com/clearlinux/ister-cloud-init-svc -.. _cloud-init Read the Docs: +.. _cloud-init: https://cloudinit.readthedocs.io diff --git a/source/clear-linux/guides/maintenance/cpu-performance.rst b/source/clear-linux/guides/maintenance/cpu-performance.rst index 10eedb6e..3a400e3c 100644 --- a/source/clear-linux/guides/maintenance/cpu-performance.rst +++ b/source/clear-linux/guides/maintenance/cpu-performance.rst @@ -33,8 +33,8 @@ C-states aim to reduce power utilization by increasingly reducing clock frequency, voltages, and features in each state. Although C-states can typically be limited or disabled in a system's UEFI or -BIOS configuration, these settings are overridden when the `intel_idle -driver`_ is in use. +BIOS configuration, these settings are overridden when the `intel_idle driver`_ +is in use. To view the current cpuidle driver run this command in a terminal: @@ -48,7 +48,8 @@ or completely disabled with :command:`idle=poll`. .. note:: - * :command:`processor.max_cstate=0` is changed to :command:`processor.max_cstate=1` by the kernel to be a valid value. + * :command:`processor.max_cstate=0` is changed to :command:`processor.max_cstate=1` + by the kernel to be a valid value. * :command:`intel_idle.max_cstate=0` disables the Intel Idle driver, not set it to C-state 0. @@ -137,8 +138,8 @@ To change the CPU frequency scaling governor: echo performance | sudo tee /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor -The list of all governors can be found in the `Linux kernel documentation on -CPUFreq Governors`_. +The list of all governors can be found in the Linux kernel documentation on +`CPUFreq Governors`_. .. note:: @@ -185,7 +186,7 @@ bundle and add your user account to the power group: .. _`Intel P-state driver`: https://www.kernel.org/doc/Documentation/cpu-freq/intel-pstate.txt -.. _`Linux kernel documentation on CPUFreq Governors`: https://www.kernel.org/doc/Documentation/cpu-freq/governors.txt +.. _`CPUFreq Governors`: https://www.kernel.org/doc/Documentation/cpu-freq/governors.txt .. _thermald: https://01.org/linux-thermal-daemon diff --git a/source/clear-linux/guides/maintenance/developer-workstation.rst b/source/clear-linux/guides/maintenance/developer-workstation.rst index 765c44c3..0e6e1a32 100644 --- a/source/clear-linux/guides/maintenance/developer-workstation.rst +++ b/source/clear-linux/guides/maintenance/developer-workstation.rst @@ -24,7 +24,8 @@ responds to this need. Use Table 1, *Developer Profiles*, to identify the *minimum required bundles* to get started developing based on your role or project. -While your role may not neatly fit in one of these categories, consider using Table 1 as a starting point. +While your role may not neatly fit in one of these categories, consider using +Table 1 as a starting point. .. list-table:: **Table 1. Developer Profiles** :widths: 20, 20, 20, 20 @@ -102,8 +103,8 @@ Other resources for developers ----------------------------------- * `Developer Tooling Framework`_ for |CL| -* `Bundle definition files`_ +* `Bundle Definition Files`_ -.. _Bundle definition files: https://github.com/clearlinux/clr-bundles +.. _Bundle Definition Files: https://github.com/clearlinux/clr-bundles .. _Developer Tooling Framework: https://github.com/clearlinux/common diff --git a/source/clear-linux/guides/maintenance/enable-user-space.rst b/source/clear-linux/guides/maintenance/enable-user-space.rst index 1ed1fcb1..0c1fc9e7 100644 --- a/source/clear-linux/guides/maintenance/enable-user-space.rst +++ b/source/clear-linux/guides/maintenance/enable-user-space.rst @@ -52,7 +52,8 @@ To be able to execute all applications with root privileges, add the Install and update the OS software to its current version ********************************************************* -The |CL| software utility :ref:`swupd ` allows you to perform system updates while reaping the benefits of upstream development. +The |CL| software utility :ref:`swupd ` allows you to perform +system updates while reaping the benefits of upstream development. To update your newly installed OS, run: @@ -69,13 +70,15 @@ to running :command:`apt-get` or :command:`yum install` for package management. Yet |CL| manages packages at the level of bundles, which are integrated stacks of packages. -For example, the `sysadmin-basic` bundle installs the majority of applications useful to a system administrator. To install it, enter: +For example, the `sysadmin-basic` bundle installs the majority of applications +useful to a system administrator. To install it, enter: .. code-block:: bash swupd bundle-add sysadmin-basic -View a full list of bundles and packages installed with the `sysadmin-basic`_ bundle. You can also view `all bundles`_ for |CL|, active or deprecated. +View a full list of bundles and packages installed with the `sysadmin-basic`_ +bundle. You can also view all `bundles`_ for |CL|, active or deprecated. Expand your knowledge of :command:`swupd` and check out our developer resources: @@ -93,7 +96,7 @@ Check out our guides and tutorials. .. _`sysadmin-basic`: https://github.com/clearlinux/clr-bundles/blob/master/bundles/sysadmin-basic -.. _`all bundles`: +.. _`bundles`: https://github.com/clearlinux/clr-bundles/tree/master/bundles .. _`wheel group`: diff --git a/source/clear-linux/guides/maintenance/kernel-development.rst b/source/clear-linux/guides/maintenance/kernel-development.rst index 91775c71..7673aec8 100644 --- a/source/clear-linux/guides/maintenance/kernel-development.rst +++ b/source/clear-linux/guides/maintenance/kernel-development.rst @@ -3,29 +3,30 @@ Kernel development ################## -This document shows how to obtain and compile a Linux* kernel source +This guide shows how to obtain and compile a Linux* kernel source using |CL-ATTR| development tooling. -The `kernels available`_ in |CL| aim to be performant and practical. In some -cases, it may be necessary to modify the kernel to suit your specific needs -or test new kernel code as a developer. +The :ref:`compatible-kernels` available in |CL| aim to be performant and +practical. In some cases, it may be necessary to modify the kernel to suit your +specific needs or test new kernel code as a developer. .. contents:: :local: :depth: 1 :backlinks: top -Source RPM files (SRPM) are also available for all |CL| kernels, and can be -used for development instead. Select this link to view the latest `source RPM files`_. +`Source RPMs (SRPMS)`_ are also available for all |CL| kernels, and can be +used for development instead. Request changes be included with the |CL| kernel ************************************************ If the kernel modification you need is already open source and likely to be useful to others, consider submitting a request to include it in the -|CL| kernels.If your change request is accepted, you do not need to maintain your own modified kernel. +|CL| kernels.If your change request is accepted, you do not need to maintain +your own modified kernel. -Make enhancement requests to the |CL| `distribution on GitHub`_ . +Make enhancement requests to the |CL| `Distribution Project`_ on GitHub. Set up kernel development environment ************************************* @@ -56,7 +57,7 @@ Clone the existing kernel package repository from |CL| as a starting point. #. Clone the Linux kernel package from |CL|. Using the :command:`make clone_` command in the :file:`clearlinux/` directory clones the package from the - `clearlinux-pkgs GitHub`_. + `clearlinux-pkgs`_ repo on GitHub. .. code-block:: bash @@ -73,7 +74,7 @@ Clone the existing kernel package repository from |CL| as a starting point. The "linux" package is the kernel that comes with |CL| in the `kernel-native` bundle. Alternatively, you can use a different kernel variant as the base for modification. For a list of kernel package names which you can clone instead, -see the `clearlinux-pkgs GitHub`_. +see the `clearlinux-pkgs`_ repo on GitHub. .. note:: @@ -261,7 +262,7 @@ consider using a patch management tool in addition to Git such as #. Generate a patch file based on your git commits. represents the number of local commits to create patch file. - See the `git-format-patch Documentation`_ for detailed information + See the `git-format-patch`_ documentation for detailed information on using :command:`git format-patch` .. code-block:: bash @@ -355,7 +356,7 @@ are persistent and distributed with a customized kernel. #. Commit and save the changes to the :file:`cmdline` file. -See the `Kernel parameters documentation`_ for a list of available +See the `kernel parameters`_ documentation for a list of available parameters. Build and install the kernel @@ -374,7 +375,9 @@ isolate building of packages in a sanitized workspace. make build .. note:: - The `ccache plugin for mock`_ can be enabled to help speed up any future rebuilds of the kernel package by caching compiler outputs and reusing them. + The mock plugin `ccache`_ can be enabled to help speed up any future + rebuilds of the kernel package by caching compiler outputs and reusing + them. #. The result will be multiple :file:`.rpm` files in the :file:`rpms` @@ -426,22 +429,18 @@ Related topics * :ref:`kernel-modules` * :ref:`mixer` -.. _kernels available: https://clearlinux.org/documentation/clear-linux/reference/compatible-kernels +.. _Distribution Project: https://github.com/clearlinux/distribution/issues/new/choose -.. _distribution on GitHub: https://github.com/clearlinux/distribution/issues/new/choose - -.. _source RPM files: https://cdn.download.clearlinux.org/current/source/SRPMS/ +.. _Source RPMs (SRPMS): https://cdn.download.clearlinux.org/current/source/SRPMS/ .. _Quilt: http://savannah.nongnu.org/projects/quilt -.. _clearlinux-pkgs GitHub: https://github.com/clearlinux-pkgs +.. _clearlinux-pkgs: https://github.com/clearlinux-pkgs .. _kernel.org: https://www.kernel.org/ -.. _Kernel parameters documentation: https://www.kernel.org/doc/Documentation/admin-guide/kernel-parameters.txt +.. _kernel parameters: https://www.kernel.org/doc/Documentation/admin-guide/kernel-parameters.txt -.. _ccache plugin for mock: https://fedoraproject.org/wiki/Mock/Plugin/CCache?rd=Subprojects/Mock/Plugin/CCache +.. _ccache: https://fedoraproject.org/wiki/Mock/Plugin/CCache?rd=Subprojects/Mock/Plugin/CCache -.. _git-format-patch Documentation: https://git-scm.com/docs/git-format-patch - -.. _user-setup script: https://github.com/clearlinux/common/blob/master/user-setup.sh \ No newline at end of file +.. _git-format-patch: https://git-scm.com/docs/git-format-patch diff --git a/source/clear-linux/guides/maintenance/kernel-modules-dkms.rst b/source/clear-linux/guides/maintenance/kernel-modules-dkms.rst index 8c8ca6ad..524a5c66 100644 --- a/source/clear-linux/guides/maintenance/kernel-modules-dkms.rst +++ b/source/clear-linux/guides/maintenance/kernel-modules-dkms.rst @@ -8,12 +8,10 @@ kernel modules that are not part of the Linux source tree, you may need to build out-of-tree kernel modules. Use this guide to add kernel modules with :abbr:`DKMS (Dynamic Kernel Module System)` or refer to :ref:`kernel-modules`. - .. contents:: :local: :depth: 1 :backlinks: top - Description *********** @@ -110,7 +108,7 @@ Build, install, and load an out-of-tree module Follow the steps in this section if you are an individual user or testing, and you need an out-of-tree kernel module that is not available through |CL|. For a more scalable and customizable approach, we recommend using the -`mixer tool`_ to provide a custom kernel and updates. +:ref:`mixer` tool to provide a custom kernel and updates. Prerequisites @@ -218,10 +216,10 @@ Here are some additional resources that can be used for reference: * DKMS manual page (:command:`man dkms`) shows detailed syntax in the DKMS.CONF section. -* `Ubuntu community wiki`_ shows an example where a single package contains - multiple modules. +* Ubuntu community wiki entry for the `Kernel DKMS Package`_ shows an example + where a single package contains multiple modules. -* `Sample dkms.conf file`_ in the GitHub\* repository for the DKMS project. +* Sample `dkms.conf`_ file in the GitHub\* repository for the DKMS project. .. note:: @@ -315,20 +313,14 @@ Examples Related topics ************** -* `Dynamic Kernel Module System (DKMS) project on GitHub `_ +* `Dynamic Kernel Module System (DKMS)`_ * `Dell Linux Engineering Dynamic Kernel Module Support: From Theory to Practice `_ * `Linux Journal: Exploring Dynamic Kernel Module Support `_ +.. _Dynamic Kernel Module System (DKMS): https://github.com/dell/dkms -.. _`on GitHub`: https://github.com/clearlinux/distribution - -.. _`mixer tool`: https://clearlinux.org/features/mixer-tool - -.. _`Dynamic Kernel Module System (DKMS)`: https://github.com/dell/dkms - -.. _Ubuntu community wiki: https://help.ubuntu.com/community/Kernel/DkmsDriverPackage#Configure_DKMS - -.. _Sample dkms.conf file: https://github.com/dell/dkms/blob/master/sample.conf +.. _Kernel DKMS Package: https://help.ubuntu.com/community/Kernel/DkmsDriverPackage#Configure_DKMS +.. _dkms.conf: https://github.com/dell/dkms/blob/master/sample.conf diff --git a/source/clear-linux/guides/maintenance/kernel-modules.rst b/source/clear-linux/guides/maintenance/kernel-modules.rst index 357bc405..d128823c 100644 --- a/source/clear-linux/guides/maintenance/kernel-modules.rst +++ b/source/clear-linux/guides/maintenance/kernel-modules.rst @@ -56,7 +56,8 @@ If the kernel module you need is already open source (for example, in the Linux upstream) and likely to be useful to others, consider submitting a request to add or enable it in the |CL| kernel. -Make enhancement requests to the |CL| distribution `on GitHub`_. +Make enhancement requests to the |CL| +`Distribution Project `_ on GitHub. .. _kernel-modules-availability-end: @@ -67,7 +68,7 @@ Build, install, and load an out-of-tree module Follow the steps in this section if you are an individual user or testing, and you need an out-of-tree kernel module that is not available through |CL|. For a more scalable and customizable approach, we recommend using the -`mixer tool`_ to provide a custom kernel and updates. +:ref:`mixer` tool to provide a custom kernel and updates. Prerequisites @@ -215,7 +216,3 @@ Related topic ************* * :ref:`kernel-modules-dkms` - - -.. _`on GitHub`: https://github.com/clearlinux/distribution -.. _`mixer tool`: https://clearlinux.org/features/mixer-tool