Merge pull request #32 from 01org/cl-restructure

Restructures Clear Linux documentation to have five main sections
2026-08-24 08:48:15 +00:00 · 2017-08-31 16:24:25 -05:00
parent 88849819fd 8058630a52
commit 2adb780198
59 changed files with 274 additions and 171 deletions
@@ -1,10 +0,0 @@
-Bundles
-#######
-
-.. toctree::
-   :maxdepth: 2
-
-   overview
-   containers-basic
-   openssh-server
-   os-core
@@ -3,12 +3,22 @@
 Clear Linux\* Project for Intel® Architecture
 #############################################

+Welcome to the |CLOSIA| documentation pages. Our documentation is split into
+five sections: Get started, Concepts, Guides, Tutorials, and Reference.
+Under :ref:`get-started`, you can find information about installing |CL| on
+bare metal, in a virtual environment, or as a live image on a USB stick. Under
+the :ref:`concepts` section, you can find detailed technical information about
+the |CL| features. The :ref:`guides` section contains step-by-step
+instructions to complete common tasks. The :ref:`tutorials` section contains
+step-by-step instructions to complete the installation and configuration of
+tools needed for a specific use case. Lastly, the :ref:`reference` section
+contains information providing additional context or details.
+
 .. toctree::
    :maxdepth: 2

-    getting-started/getting-started
-    bundles/bundles
-    how-to/how-to
-    network/network
-    virtual-environments/virtual-environments
-    tutorials/tutorials
+    get-started/get-started
+    concepts/concepts
+    guides/guides
+    tutorials/tutorials
+    reference/reference
@@ -0,0 +1,31 @@
+.. _bundles-about:
+
+Bundles
+#######
+
+Linux-based operating systems contain the code of several hundred, if
+not thousands, of open source projects. To make this manageable,
+distributions use a concept called "packages" to configure and compile
+the source code of these projects into binaries.
+
+Many distributions then split the content of these compiled packages
+into so-called sub-packages, which are the granularity at which these
+distributions deploy their software. With those kinds of distributions,
+system administrators can then install and update sub-packages
+individually or as a set, using tools such as "yum" and "apt-get."
+
+The |CLOSIA| takes a slightly different approach. While we also use the
+concept of packages to manage compiling source code into binaries, we do not
+use the package concept to deploy software. Instead, we provide software
+"bundles" that are installed and managed using :ref:`swupd<swupd-about>`. Each
+bundle contains as many or as few open source projects needed to provide a
+complete functionality.
+
+Next steps
+==========
+
+To put this concept into practice, see the following resources:
+
+* :ref:`available-bundles`
+* :ref:`bundle-commands`
+* :ref:`compatible-kernels`
@@ -0,0 +1,14 @@
+.. _concepts:
+
+Concepts
+########
+
+The concepts section provides content for a deeper understanding of the
+features of |CLOSIA|. These concepts attempt to provide all the technical
+details relevant to the |CL| features.
+
+.. toctree::
+   :maxdepth: 1
+
+   swupd-about
+   bundles-about
@@ -1,7 +1,7 @@
 .. _swupd-about:

-About software update
-#####################
+Software update
+###############

 The traditional way
 ===================
@@ -129,6 +129,7 @@ system and its updates as the basis. Using this tool, system administrators
 can focus on the custom pieces their deployments require while staying on
 a controlled update stream.

+To learn how to run an update of your system, visit our :ref:`update` page.

 .. [1] The software update technology for Clear Linux* OS for Intel
   Architecture was first presented at the Linux Plumbers conference in 2012.
@@ -1,6 +1,6 @@
 .. _bare-metal-install:

-Clear Linux host OS install on bare metal
+Install Clear Linux host OS on bare metal
 #########################################

 These instructions will guide you through the installation of |CL| on bare
@@ -8,7 +8,7 @@ metal using a :ref:`bootable USB drive<create-usb>`.

 Verify your system hardware is supported by |CLOSIA|. Review the
 :ref:`list of supported processors <supported-hardware>` and
-:ref:`instructions to run a compatibility check <check-compatibility>`.
+:ref:`instructions to run a compatibility check <compatibility-check>`.

 .. note::

@@ -337,7 +337,7 @@ Next steps

 With your system now running |CL| many paths are open for you.

-Visit our :ref:`tutorials <tutorials>` page for examples on using your |CL|
+Visit our :ref:`tutorials` page for examples on using your |CL|
 system.

 .. _`NUC6i5SYH product page`:
@@ -1,4 +1,4 @@
-.. _check-compatibility:
+.. _compatibility-check:

 Check system compatibility with Clear Linux OS for Intel® Architecture
 ######################################################################
@@ -0,0 +1,21 @@
+.. _get-started:
+
+Get started
+###########
+
+This section contains information about the installation of |CLOSIA|.
+
+The :ref:`get-started` section provides step-by-step instructions to download
+and run |CL| on :ref:`bare metal <bare-metal-install>`, under
+a :ref:`virtual machine <virtual-machine-install>`, or by way of a
+:ref:`live image <live-image>`. Additionally, it provides useful pre-install
+information and instructions on how to complete pre-install tasks.
+
+.. toctree::
+   :maxdepth: 1
+
+   bare-metal-install/bare-metal-install
+   virtual-machine-install/virtual-machine-install
+   live-image
+   compatibility-check
+   ../reference/supported-hardware
@@ -1,7 +1,7 @@
 .. _live-image:

-Live Image Installation
-#######################
+Install Clear Linux as a live image
+###################################

 This option is a great way to try a live |CL| environment without writing
 to your computer's hard disk.
@@ -1,7 +1,7 @@
 .. _hyper-v:

-Using Hyper-V\*
-###############
+Use Hyper-V\*
+#############

 This section explains how to run |CLOSIA| inside a
 `Windows Server Virtualization`_\* or **Hyper-V** environment.
@@ -58,4 +58,3 @@ Your virtual machine running |CLOSIA| is ready!
 .. _Microsoft documentation: https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/quick-start/enable-hyper-v
 .. _Create A Virtual Network documentation: https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/quick-start/connect-to-network
 .. _downloads: https://download.clearlinux.org/image/
-
@@ -1,7 +1,7 @@
 .. _kvm:

-Using KVM
-#########
+Use KVM
+#######

 The easiest way to get started in a virtualized environment is to download
 a recent KVM image from the `images`_ directory. Here you'll find a kvm
@@ -0,0 +1,36 @@
+.. _virtual-machine-install:
+
+Install Clear Linux in a virtual machine
+########################################
+
+There are some considerations to make when installing |CL| in a VM.
+First, you need to decide which kernel to use. This document
+will walk you through the available kernel options to help this decision. At
+the end of this document, you will be able to select the set of installation
+steps most suitable to you and install |CL| under a VM.
+
+Compatible kernels
+==================
+
+The |CLOSIA| provides the following Linux kernels with a respective
+:ref:`bundle <bundles-about>` for VMs. Specific use cases these bundles serve
+are provided along with links to their source code.
+
+.. include:: ../../reference/compatible-kernels.rst
+   :Start-after: vm-kernels:
+
+Next steps:
+===========
+
+Now that you have read about the |CL| compatible kernels, choose the
+appropriate set of step-by-step instructions to proceed.
+
+.. toctree::
+   :maxdepth: 1
+
+   kvm
+   virtualbox
+   vmware-esxi
+   vmware-player
+   hyper-v
+
@@ -1,7 +1,7 @@
 .. _virtualbox:

-Using VirtualBox\*
-##################
+Use VirtualBox\*
+################

 This section explains how to run |CLOSIA| inside a `VirtualBox environment`_.

@@ -1,7 +1,7 @@
 .. _vmware-esxi:

-Using VMware\* ESXi guest
-##########################
+Use VMware\* ESXi guest
+#######################


 This section is based on *VMware vSphere 6* and explains how to use |CLOSIA|
@@ -1,7 +1,7 @@
 .. _vmware-player:

-Using VMware\* Player
-#####################
+Use VMware\* Player
+###################

 This section explains how to run Clear Linux OS for Intel® Architecture
 within a `VMware Player`_ environment.
@@ -1,17 +0,0 @@
-.. _getting-started:
-
-Getting started
-###############
-
-There are a number of options available for downloading and running
-|CLOSIA|. Using different kernels, you can install |CL| under virtual
-machines, containers, on bare metal, or by way of live image.
-
-.. toctree::
-   :maxdepth: 2
-
-   kernels
-   bare-metal-install/bare-metal-install
-   supported-hardware
-   check-compatibility
-   live-image
@@ -0,0 +1,13 @@
+.. _guides:
+
+Guides
+######
+
+The following guides provide step-by-step instructions for tasks that come
+after completing the |CL| :ref:`installation <get-started>`.
+
+.. toctree::
+   :maxdepth: 2
+
+   maintenance/maintenance
+   network/network
@@ -1,7 +1,7 @@
-.. _bulk-provisioning:
+.. _bulk-provision:

-Bulk Provisioning
-#################
+Bulk provision
+##############

 The |CLOSIA| can be automatically provisioned in bulk using a combination of
 the |CL| installer, **Ister**, and :abbr:`ICIS (Ister Cloud Init Service)`.
@@ -49,7 +49,7 @@ Configuration
   with the steps it needs to perform an installation. The file outlines
   what partitions, file systems, and mount points **Ister** should set
   up. Lastly, the file outlines which bundles to install. See our
-   :ref:`overview` for the list of available bundles. The
+   :ref:`available-bundles` document for the list of available bundles. The
   following example shows the contents of an Ister installation file:

   .. code-block:: json
@@ -0,0 +1,15 @@
+.. _maintenance:
+
+Maintenance guide
+#################
+
+This guide provides step-by-step instructions for common tasks associated with
+maintaining |CLOSIA| after :ref:`installation <get-started>` is completed.
+
+.. toctree::
+   :maxdepth: 2
+
+   update
+   bulk-provision
+   mixer
+   validate-signatures
@@ -1,7 +1,7 @@
 .. _mixer:

-Mixer tool
-##########
+Use mixer tool
+##############

 *Mixing* refers to composing an operating system for specific use cases. While
 the default Clear Linux\* OS for Intel® Architecture provides options to
@@ -1,7 +1,7 @@
-.. _swupd-run:
+.. _update:

-How to update Clear Linux
-#########################
+Update Clear Linux
+##################

 This section describes how to update |CLOSIA|.

@@ -1,7 +1,7 @@
 .. _validate-signatures:

-Validating signatures
-#####################
+Validate signatures
+###################

 |CLOSIA| offers a way to validate the content of an image or an update. All
 validation of content works by creating and signing a hash. A valid signature
@@ -1,7 +1,7 @@
 .. _dpdk:

-DPDK
-####
+Send packages between platforms
+###############################

 :abbr:`Data Plane Development Kit (DPDK)` is a set of libraries and drivers
 for fast packet processing. This document describes how to run a basic use
@@ -1,7 +1,7 @@
 .. _network-bonding:

-Network Bonding
-###############
+Combine multiple interfaces
+###########################

 Network bonding is a technique for combining multiple network interfaces into
 a single, logical interface, providing some redundancy and bandwidth
@@ -1,7 +1,7 @@
 .. _network-boot:

-Network Booting
-###############
+Boot from PXE
+#############

 |CLOSIA| can boot from a :abbr:`PXE (pre-boot execution environment)`. PXE
 is an industry standard which describes the client-server interaction to
@@ -0,0 +1,15 @@
+.. _network:
+
+Network guide
+#############
+
+This guide provides step-by-step instructions for common tasks associated with
+the configuration, administration, and use of networks in the |CLOSIA|.
+
+.. toctree::
+    :maxdepth: 1
+
+    network-boot
+    dpdk
+    ovs-dpdk
+    network-bonding
@@ -1,7 +1,7 @@
 .. _ovs-dpdk:

-OpenvSwitch and DPDK
-####################
+Enable DPDK support on OpenvSwitch
+##################################

 Enabling `DPDK`_ support on the `OpenvSwitch`_ project can yield significant
 network performance improvements. To illustrate one such example, we'll cover
@@ -1,14 +0,0 @@
-.. _how-to:
-
-Clear Linux\* OS How to guides
-##############################
-
-.. toctree::
-   :maxdepth: 2
-
-   azure
-   swupd/about
-   swupd/run
-   bulk-provisioning
-   mixer
-   validate-signatures
@@ -1,12 +0,0 @@
-.. _network:
-
-Clear Linux\* OS Network guides
-###############################
-
-.. toctree::
-    :maxdepth: 2
-
-    network-boot
-    dpdk
-    ovs-dpdk
-    network-bonding
@@ -0,0 +1,22 @@
+.. _bundle-commands:
+
+Useful bundle commands
+######################
+
+To see a list of currently-installed bundles, enter:
+
+.. code-block:: console
+
+   # swupd bundle-list
+
+To see the list of all available bundles, enter:
+
+.. code-block:: console
+
+   # swupd bundle-list --all
+
+To add a bundle, enter:
+
+.. code-block:: console
+
+   # swupd bundle-add [bundle name]
@@ -1,51 +1,22 @@
-.. _overview:
+.. _available-bundles:

-Bundles overview
-################
+Available bundles
+#################

-Linux-based operating systems contain the code of several hundred, if
-not thousands, of open source projects. To make this manageable,
-distributions use a concept called "packages" to configure and compile
-the source code of these projects into binaries.
+This document provides a current list of available `bundles`_ as of
+``[[24 April 2017]]``.

-Many distributions then split the content of these compiled packages
-into so-called sub-packages, which are the granularity at which these
-distributions deploy their software. With those kinds of distributions,
-system administrators can then install and update sub-packages
-individually or as a set, using tools such as ``yum`` and ``apt-get``.
+See in depth descriptions of the following bundles:

-The |CLOSIA| takes a slightly different
-approach. While we also use the concept of packages to manage compiling
-source code into binaries, we do not use the package concept to deploy
-software. Instead, we provide "bundles" that  provide a set of functionality
-to the system administrator, independent of how many and which pieces of
-the upstream open source projects are needed for this functionality.
+.. toctree::
+   :maxdepth: 1

-Useful bundle commands
-======================
+   containers-basic
+   openssh-server
+   os-core.rst

-To see a list of currently-installed bundles, enter:
-
-.. code-block:: console
-
-   # swupd bundle-list
-
-To see the list of all available bundles, enter:
-
-.. code-block:: console
-
-   # swupd bundle-list --all
-
-To add a bundle, enter:
-
-.. code-block:: console
-
-   # swupd bundle-add [bundle name]
-
-Bundle overview table
-=====================
-
-Current list of available bundles as of ``[[24 April 2017]]``.
+Bundle list
+===========

 .. raw:: html

@@ -1040,3 +1011,4 @@ Current list of available bundles as of ``[[24 April 2017]]``.
       </tbody>
   </table>

+.. _bundles: https://github.com/clearlinux/clr-bundles
@@ -1,7 +1,7 @@
-.. _kernels:
+.. _compatible-kernels:

-Compatible |CL| kernels
-#######################
+Compatible Clear Linux kernels
+##############################

 The |CLOSIA| provides the following Linux kernels with a respective bundle.
 This document describes the specific use cases these `bundles`_ serve
@@ -15,6 +15,17 @@ optimized for fast booting and performs best on the Intel® architectures
 described on the :ref:`supported hardware list<supported-hardware>`. The
 optimization patches are found in our `Linux`_ GitHub\* repo.

+Kernel Container
+================
+
+The *kernel-container* bundle contains the kernel used by the
+`Intel® Clear Containers`_ project. This kernel is optimized for
+fast booting and performs best on |CC| running on the Intel® architectures
+described on the :ref:`supported hardware list<supported-hardware>`.
+The optimization patches are found in our `Linux-Container`_ GitHub repo.
+
+.. _vm-kernels:
+
 Kernel LTS
 ==========

@@ -67,14 +78,6 @@ alone Linux VM, see our :ref:`instructions on using Hyper-V<hyper-v>` for
 more information. The optimization patches are found in our
 `Linux-HyperV-LTS`_ GitHub repo.

-Kernel Container
-================
-
-The *kernel-container* bundle contains the kernel used by the
-`Intel® Clear Containers`_ project. This kernel is optimized for
-fast booting and performs best on |CC| running on the Intel® architectures
-described on the :ref:`supported hardware list<supported-hardware>`.
-The optimization patches are found in our `Linux-Container`_ GitHub repo.

 .. _Linux: https://github.com/clearlinux-pkgs/linux
 .. _Linux-LTS: https://github.com/clearlinux-pkgs/linux-lts
@@ -0,0 +1,15 @@
+.. _reference:
+
+Reference
+#########
+
+This section contains content which provides additional information
+regarding the |CL| project and the |CL| features.
+
+.. toctree::
+   :maxdepth: 2
+
+   bundle-commands
+   bundles/available-bundles
+   compatible-kernels
+   supported-hardware
@@ -23,7 +23,7 @@ system to determine whether it will work with the latest release:
 .. toctree::
    :maxdepth: 1

-    compatibility-check.rst
+    ../get-started/compatibility-check.rst

 .. note::

@@ -3,12 +3,14 @@
 Tutorials
 #########

+This section provides detailed instructions to guide you through completing
+specific |CLOSIA| use cases.
+
 .. toctree::
   :maxdepth: 2

-   wordpress.rst
-   flatpak/flatpak.rst
+   wordpress
+   flatpak/flatpak
   machine-learning/machine-learning
+   azure
   multi-boot/multi-boot
-
-
@@ -9,7 +9,7 @@ to guide you to a fully realized WordPress website using |CLOSIA|.
 In this tutorial we assume your system is already running |CL|. For
 instructions on how to install |CL| on bare metal, see the
 :ref:`bare metal install<bare-metal-install>` page from our
-:ref:`getting started<getting-started>` guide. For your convenience, we have
+:ref:`get-started` guide. For your convenience, we have
 split this tutorial in two different sections.  If you already have a |CL|
 based :abbr:`LAMP (Linux, Apache, MySQL, PHP)` web server you can skip ahead
 to the WordPress tutorial.
@@ -1,7 +1,7 @@
 .. _wp-install:

-Creating a Clear Linux WordPress* server
-########################################
+Create a Clear Linux WordPress\* server
+#######################################

 Prerequisites
 =============
@@ -1,13 +0,0 @@
-.. _virtual-environments:
-
-Running in virtual environments
-###############################
-
-.. toctree::
-   :maxdepth: 2
-
-   kvm
-   virtualbox
-   vmware-esxi
-   vmware-player
-   hyper-v