(SIMP-1850) Doc Cleanup

Performed various documentation cleanup:
  * Added a 'one page' quickstart
  * Reorganized the building sections
  * Added a section on building via Rake
  * Updated the Glossary
  * Fixed several typos
  * Fixed some minor grammar issues
  * Added all latest releases to the Supported Versions page

SIMP-1850 #comment Attempting to make getting started easier

Change-Id: I38376f98ad5f56299e43bb89b3d12e39a1bc9c2d

docs/common/SIMP_Overview.rst

@@ -1,15 +1,16 @@
-The System Integrity Management Platform (SIMP) is a framework designed
-around the concept that individuals and organizations should not need to repeat
-the work of automating the basic components of their operating system infrastructure.
+The System Integrity Management Platform (:term:`SIMP`) is an
+:term:`Open Source` framework designed around the concept that individuals and
+organizations should not need to repeat the work of automating the basic
+components of their operating system infrastructure.
 
 Expanding upon this philosophy, SIMP also aims to take care of routine policy
-compliance to include NIST 800-53, FIPS 140-2, the DISA STIG, and the SCAP
-Security Guides.
+compliance to include :term:`NIST 800-53`, :term:`FIPS` 140-2, the
+:term:`DISA STIG`, and the :term:`SCAP Security Guide`.
 
-By using the :term:`Puppet` automation stack, SIMP is working toward the concept of a
-self-healing infrastructure that, when used with a consistent configuration
-management process, will allow users to have confidence that their systems not
-only start in compliance but remain in compliance over time.
+By using the :term:`Puppet` automation stack, SIMP is working toward the
+concept of a self-healing infrastructure that, when used with a consistent
+configuration management process, will allow users to have confidence that
+their systems not only start in compliance but remain in compliance over time.
 
 Finally, SIMP has a goal of remaining flexible enough to properly maintain your
 operational infrastructure. To this end, where possible, the SIMP components

docs/conf.py

@@ -160,31 +160,63 @@
 if os_ver_mapper_content != None:
     os_flavors = None
     ver_map = yaml.load(os_ver_mapper_content)
-    if version in ver_map['simp_releases']:
-        os_flavors = ver_map['simp_releases'][version]['flavors']
-    elif full_version in ver_map['simp_releases']:
-        os_flavors = ver_map['simp_releases'][full_version]['flavors']
-    elif version_family in ver_map['simp_releases']:
-        os_flavors = ver_map['simp_releases'][version_family]['flavors']
-
-    # Extract the actual OS version supported for placement in the docs
-    if os_flavors is not None:
-        if os_flavors['RedHat']:
-            ver_list = os_flavors['RedHat']['os_version'].split('.')
-            el_major_version = ver_list[0]
-            el_minor_version = ver_list[1]
-        elif os_flavors['CentOS']:
-            ver_list = os_flavors['CentOS']['os_version'].split('.')
-            el_major_version = ver_list[0]
-            el_minor_version = ver_list[1]
-
-        # Build the Release mapping table for insertion into the docs
-        release_mapping_list = []
-        for os_flavor in os_flavors:
-            release_mapping_list.append('* **' + os_flavor + ' ' + os_flavors[os_flavor]['os_version'] + '**')
-            for i, iso in enumerate(os_flavors[os_flavor]['isos']):
-                release_mapping_list.append("\n   * **ISO #" + str(i+1) + ":** " + iso['name'])
-                release_mapping_list.append("   * **Checksum:** " + iso['checksum'])
+
+    map_versions = sorted(ver_map['simp_releases'].keys(), reverse=True)
+
+    unstable_releases = []
+    for map_version in map_versions:
+        if re.search('\.X$', map_version):
+            unstable_releases.append(map_version)
+
+    unstable_releases = sorted(unstable_releases, reverse=True)
+
+    major_releases = []
+    for head_release in unstable_releases:
+        major_version = head_release.split('.')[0]
+        if re.search('^' + major_version + '\.', head_release):
+            major_releases.append(major_version)
+
+    head_releases = []
+    major_found = []
+    for map_version in map_versions:
+        major_version = map_version.split('.')[0]
+        if major_version in major_found:
+            continue
+
+        if re.search('^' + major_version + '\.', map_version):
+            head_releases.append(map_version)
+            major_found.append(major_version)
+
+    # Smash the current release onto the front of the list
+    all_releases = head_releases + unstable_releases
+
+    # If we don't have the full version, don't just drop in an empty key
+    if full_version in all_releases:
+        all_releases.remove(full_version)
+        all_releases.insert(0, full_version)
+
+    # Build the Release mapping table for insertion into the docs
+    release_mapping_list = []
+    for release in all_releases:
+        os_flavors = ver_map['simp_releases'][release]['flavors']
+        release_mapping_list.append('* **SIMP ' + release + '**')
+
+        # Extract the actual OS version supported for placement in the docs
+        if os_flavors is not None:
+            if os_flavors['RedHat']:
+                ver_list = os_flavors['RedHat']['os_version'].split('.')
+                el_major_version = ver_list[0]
+                el_minor_version = ver_list[1]
+            elif os_flavors['CentOS']:
+                ver_list = os_flavors['CentOS']['os_version'].split('.')
+                el_major_version = ver_list[0]
+                el_minor_version = ver_list[1]
+
+            for os_flavor in os_flavors:
+                release_mapping_list.append("\n    * **" + os_flavor + ' ' + os_flavors[os_flavor]['os_version'] + '**')
+                for i, iso in enumerate(os_flavors[os_flavor]['isos']):
+                    release_mapping_list.append("\n      * **ISO #" + str(i+1) + ":** " + iso['name'])
+                    release_mapping_list.append("      * **Checksum:** " + iso['checksum'])
 
         # Trailing newline
         release_mapping_list.append('')

docs/getting_started_guide/Building_A_SIMP_ISO.rst

@@ -0,0 +1,20 @@
+Building a SIMP ISO
+===================
+
+If you want the full SIMP experience where you maximize compliance with the
+widest selection of targeted standards, you'll want to build and install from a
+SIMP ISO.
+
+The following guides provide an overview of the supported build methods.
+
+.. WARNING::
+  Prior to starting any build method, you will need to ensure that you follow
+  the instructions in :ref:`gsg-environment_preparation`.
+
+.. toctree::
+  :maxdepth: 2
+
+  ISO_Build/Environment_Preparation
+  ISO_Build/Building_SIMP_From_Tarball
+  ISO_Build/Building_SIMP_From_Source
+  ISO_Build/Building_SIMP_Via_Rake

docs/getting_started_guide/Building_SIMP_From_Source.rst → docs/getting_started_guide/ISO_Build/Building_SIMP_From_Source.rst

@@ -1,10 +1,12 @@
+.. _gsg-building_simp_from_source:
+
 Building SIMP From Source
 =========================
 
 Getting Started
 ---------------
 
-Please have your environment prepared as specified by :ref:`Environment_Preparation` before continuing.
+Please have your environment prepared as specified by :ref:`gsg-environment_preparation` before continuing.
 
 Download the CentOS/RedHat installation media:
 

docs/getting_started_guide/Building_SIMP_From_Tarball.rst → docs/getting_started_guide/ISO_Build/Building_SIMP_From_Tarball.rst

@@ -1,45 +1,64 @@
+.. _gsg-building_simp_from_tarball:
+
 Building SIMP From Tarball
 ==========================
 
+.. NOTE::
+  Building SIMP from a pre-built tarball is the fastest method for getting a
+  known stable build of a SIMP ISO and should be preferred over other methods.
+
 Getting Started
 ---------------
 
-Please have your environment prepared as specified by :ref:`Environment_Preparation` before continuing.
+.. WARNING::
+  Please have your environment prepared as specified by
+  :ref:`gsg-environment_preparation` before continuing.
 
 .. NOTE::
-
-  You do not need ``mock`` on your system if you are generating an ISO based on the SIMP Tarball!
+  You do **not** need ``mock`` on your system if you are generating an ISO
+  based on the SIMP Tarball!
 
 Download the CentOS/RedHat installation media:
 
   * SIMP_5.X: `CentOS-7-x86_64-DVD-1511.iso`_
-  * SIMP_4.X: `DVD1 and DVD2`_ of the CentOS 6.8 release. For example, CentOS-6.8-x86_64-bin-DVD1.iso
+  * SIMP_4.X: `DVD1 and DVD2`_ of the CentOS 6.8 release. For example,
+    ``CentOS-6.8-x86_64-bin-DVD1.iso``
 
 Download the SIMP release tarball, found on our `BinTray artifacts repository`_.
 
+Download the latest tarball according to your needs. If you are not sure what
+version you need, check the :ref:`faq-simp_version_guide`.
+
   * The `latest 5.2.0-0 release (for CentOS 7)`_
   * The `latest 4.3.0-0 release (for CentOS 6)`_
 
 Generating The ISO!
 -------------------
 
-Change into the ``simp-core`` directory and make sure you are on the correct branch for your target SIMP version:
+Change into the ``simp-core`` directory and make sure you are on the correct
+branch for your target SIMP version:
 
 .. code::
 
    $ cd simp-core
    $ git checkout 5.1.X # for SIMP 5 and CentOS 7
    $ git checkout 4.2.X # for SIMP 4 and CentOS 6
 
-Run ``bundle`` to make sure that all of the build tools and dependencies are installed and up to date:
+Run ``bundle install`` to make sure that all of the build tools and dependencies are
+installed and up to date:
 
 .. code::
 
-   $ bundle
+   $ bundle install
+
+Make sure all of the source materials that were downloaded above are in your
+current working directory.
 
-Make sure all of the source materials that were downloaded above are in your current working directory.
+Run the ``build:auto`` rake task to create a bootable ISO:
 
-Run the ``build:auto`` rake task to create a bootable ISO using the following template:
+.. NOTE::
+  Do **not** add any whitespace before or after the commas. This is an artiface
+  of using ``rake``.
 
 .. code::
 
@@ -55,7 +74,8 @@ For example:
    $ # for SIMP 4 and CentOS 6
    $ bundle exec rake build:auto[4.2.X,.,SIMP-DVD-CentOS-4.3.0-0.tar.gz]
 
-Once the process completes, you should have a bootable SIMP ISO ready for installation!
+Once the process completes, you should have a bootable SIMP ISO ready for
+installation!
 
 
 .. _BinTray artifacts repository: https://bintray.com/simp/Releases/Artifacts#files

docs/getting_started_guide/ISO_Build/Building_SIMP_Via_Rake.rst

@@ -0,0 +1,98 @@
+.. _gsg-building_simp_via_rake:
+
+Building SIMP via Rake
+======================
+
+The `simp-core`_ acceptance tests provide a method for building the SIMP ISOs
+directly from online resources and is the method that the SIMP team uses to
+ensure clean ISO builds.
+
+.. NOTE::
+   This method is **slow** but requires the least amount of modification to
+   your build system.
+
+.. WARNING::
+   This method will only work on ``simp-core`` repositories that respond to
+   ``rake build:auto``.
+
+Getting Started
+---------------
+
+.. WARNING::
+   Please have your environment prepared as specified by
+   :ref:`gsg-environment_preparation` before continuing.
+
+.. NOTE::
+   You do **not** need ``mock`` on your system if you are using this method.
+
+.. IMPORTANT::
+   You **must** have Internet accessibility for this method to work!
+
+Install Either Docker or VirtualBox
+-----------------------------------
+
+This build method relies on :term:`Beaker` from Puppet, Inc. and can use either
+:term:`Docker` or :term:`VirtualBox` as the build back-end. The Docker method
+is faster but the VirtualBox method is far easier to debug if issues arise.
+
+You must have a working :term:`Vagrant` installation to use this method.
+
+.. NOTE::
+  Make sure that you use the Vagrant installation directly from the
+  `Vagrant Homepage`_.
+
+Download the Appropriate EL ISO
+-------------------------------
+
+You will need to download the correct :term:`EL` ISO for the version of SIMP
+that you are trying to build. If you have doubts, check the
+``build/release_mappings.yaml`` file.
+
+The ISOs should be downloaded into the ``spec/fixtures/ISO`` directory (that
+you create).
+
+Required Environment Variables
+------------------------------
+
+If you simply run the :term:`rake` commands, the system will attempt to build
+**all** versions of SIMP that are coded into the tests.
+
+If you want to build a specific version of SIMP, you must use the following
+environment variables.
+
+SIMP_BEAKER_build_version
+  The git branch or tag that you want to build
+
+SIMP_BEAKER_build_map
+  The ``release_mapper.yaml`` key that you want to use.
+  Defaults to ``SIMP_BEAKER_build_version`` if not specified.
+
+Build Using Docker
+------------------
+
+The :term:`Docker` method is the faster of the two methods but can make
+debugging quite difficult if something goes wrong.
+
+To build the suite via Docker run the following command:
+
+.. code::
+
+  $ rake beaker:suites[default]
+
+Build Using VirtualBox
+----------------------
+
+If you wish to build using :term:`VirtualBox` simply run the following command:
+
+.. code::
+
+  $ rake beaker:suites[iso_vbox]
+
+Results
+-------
+
+The ISOs from the :term:`rake` commands will be placed under a
+``SIMP_ISO/rake_generated/<branch>/<timestamp>`` directory structure.
+
+.. _simp-core: https://github.com/simp/simp-core
+.. _Vagrant Homepage: https://www.vagrantup.com/downloads.html