(SIMP-4) Fix errors during documentation builds

This commit fixes various ReST compilation errors. Most of the errors were non-fatal problems with the ReST markup genrated by pandoc when the Publican documentation was originally converted. The two most common problems were unknown lexer errors and 'document isn't included in any toctree' warnings. SIMP-349 #comment Fixed unknown lexer errors for 4.2.X SIMP-350 #comment Fixed ReST toctree errors for 4.2.X SIMP-348 #comment Fixed sphinx compilation errors for 4.2.X SIMP-4 #comment Fixed sphinx compilation errors for 4.2.X
simp · Aug 4, 2015 · 7a2e304 · 7a2e304
1 parent b85469b
commit 7a2e304
Show file tree

Hide file tree

Showing 29 changed files with 120 additions and 122 deletions.
diff --git a/Rakefile b/Rakefile
@@ -60,4 +60,13 @@ namespace :docs do
     puts "== #{cmd}"
     %x(#{cmd} > /dev/null)
   end
+
+
+  desc 'build HTML docs (single page)'
+  task :singlehtml do
+    extra_args = ''
+    cmd = "sphinx-build -E -n #{extra_args} -b singlehtml -d sphinx_cache docs html-single"
+    puts "== #{cmd}"
+    %x(#{cmd} > /dev/null)
+  end
 end
diff --git a/docs/common/Changelog.rst b/docs/common/Changelog.rst
@@ -183,9 +183,11 @@ Fixed Bugs
     even if you didn't want to use it. This has been fixed.
   - Made the password policy overlay align with the latest SIMP build of
     the plugin.
+
     - This means that you *must* have version
       simp-ppolicy-check-password-2.4.39-0 or later available to the system
       being configured.
+
   - Change the call to the *rsyslog* init script to the *service* command to
     seamlessly support both RHEL6 and RHEL7.
   - Fixed reported bugs in syncrepl.pp.

diff --git a/docs/common/Client_Management.rst b/docs/common/Client_Management.rst
@@ -12,7 +12,7 @@ System Requirements
 Before installing clients, the system should consist of the following
 minimum requirements:
 
--  Hardware/:term:`Virtual Machine` : Capable of running RHEL 6 or 7 ; 64-bit compatible
+-  Hardware/:term:`Virtual Machine (VM)` : Capable of running RHEL 6 or 7 ; 64-bit compatible
 
 -  RAM: 512 MB
 

diff --git a/docs/common/PXE_Boot.rst b/docs/common/PXE_Boot.rst
@@ -80,7 +80,7 @@ code varies based on the model being kickstarted.
 Source Code for Setting Up TFTP on Puppet Server
 TFTP Examples
 
-.. code-block:: Ruby
+.. code-block:: ruby
 
             # Set KSSERVER statically or use Hiera for lookup
             class site::tftpboot {
@@ -115,7 +115,7 @@ example code to that yaml file.
 Source Adding TFTP Site Manifest to Hiera
 TFTP Examples
 
-.. code-block:: XML
+.. code-block:: xml
 
             ---
             classes:

diff --git a/docs/installation_guide/Certificates.rst b/docs/installation_guide/Certificates.rst
@@ -1,5 +1,3 @@
-.. _Certificates:
-
 Apply Certificates
 ==================
 

diff --git a/docs/installation_guide/Hiera_Overview.rst b/docs/installation_guide/Hiera_Overview.rst
@@ -21,7 +21,7 @@ file, say default.yaml, as such:
 
 Adding a Key/Value Pair to Hiera Examples
 
-.. code-block:: XML
+.. code-block:: xml
 
           ---
           classfoo::parameter_bar: "Woo"
@@ -74,7 +74,7 @@ Adding a Site Manifest Examples
 
 .. only:: not simp_4
 
-  .. code-block:: Ruby
+  .. code-block:: ruby
 
           # in /etc/puppet/environments/simp/modules/site/manifests/tftpboot.pp
           # Set KSSERVER statically or use Hiera for lookup
@@ -96,7 +96,7 @@ Adding a Site Manifest Examples
 
 .. only:: simp_4
 
-  .. code-block:: Ruby
+  .. code-block:: ruby
 
           # in /etc/puppet/modules/site/manifests/tftpboot.pp
           # Set KSSERVER statically or use Hiera for lookup
@@ -118,7 +118,7 @@ Adding a Site Manifest Examples
 
 Adding TFTP Site to Hiera Examples
 
-.. code-block:: XML
+.. code-block:: xml
 
           ---
           classes:

diff --git a/docs/security_conop/Appendices.rst b/docs/security_conop/Appendices.rst
@@ -1,12 +1,12 @@
 Security Concepts Appendices
 ============================
 
-:doc:`Appendix_Audit_Rules`
+.. toctree::
+  :maxdepth: 2
 
-:doc:`Appendix_KS`
+  Appendix_AIDE.rst
+  Appendix_Audit_Rules.rst
+  Appendix_KS.rst
+  Appendix_RPM.rst
+  Appendix_SCTM.rst
 
-:doc:`Appendix_AIDE`
-
-:doc:`Appendix_RPM`
-
-:doc:`Appendix_SCTM`
diff --git a/docs/security_conop/Appendix_RPM.rst b/docs/security_conop/Appendix_RPM.rst
@@ -2,7 +2,7 @@ SIMP Common RPMs
 ================
 
 CentOS RPMs
-===========
+-----------
 
 +-----------------------------------------------------------+-------------------------------+
 | RPM                                                       | URL                           |
@@ -75,7 +75,7 @@ CentOS RPMs
 Table: CentOS RPMs
 
 Common RPMs
-===========
+-----------
 
 +----------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------+
 | RPM                                                      | URL                                                                                                                |
@@ -364,7 +364,7 @@ Common RPMs
 Table: Common RPMs
 
 RHEL RPMs
-=========
+---------
 
 +--------------------------------------------+-------------------+
 | RPM                                        | URL               |

diff --git a/docs/security_conop/Appendix_SCTM.rst b/docs/security_conop/Appendix_SCTM.rst
@@ -8,7 +8,7 @@ control. Implementations are free to take these tables and use them as a
 starting point for any accreditation activities that follow NIST 800-53.
 
 SIMP SCTM Technical Controls
-============================
+----------------------------
 
 +--------------+-------------------------------------------------------------------------------------------------+----------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 | Control ID   | Control Name                                                                                    | Control Family                         | SIMP Implementation Method                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
@@ -525,7 +525,7 @@ SIMP SCTM Technical Controls
 Table: SIMP SCTM
 
 SIMP SCTM Operational Controls
-==============================
+------------------------------
 
 +--------------+----------------------------------------------------------------------------+-----------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 | Control ID   | Control Name                                                               | Control Family                          | SIMP Implementation Method                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
@@ -1036,7 +1036,7 @@ SIMP SCTM Operational Controls
 Table: SIMP SCTM
 
 SIMP SCTM Management Controls
-=============================
+-----------------------------
 
 +--------------+----------------------------------------------------------------+-----------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 | Control ID   | Control Name                                                   | Control Family                          | SIMP Implementation Method                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |

diff --git a/docs/security_conop/index.rst b/docs/security_conop/index.rst
@@ -28,3 +28,4 @@ Contents:
   Operational_Security
   System_Management
   Appendices
+
diff --git a/docs/user_guide/Book_Info.rst b/docs/user_guide/Book_Info.rst
diff --git a/docs/user_guide/FAQ.rst b/docs/user_guide/FAQ.rst
@@ -4,28 +4,19 @@ SIMP FAQs
 This chapter answers some of the frequently asked questions (FAQs) about
 SIMP.
 
-:doc:`FAQs/Centralized_Logging`
-
-:doc:`FAQs/Changing_Puppet_Masters`
-
-:doc:`FAQs/DVD_Build`
-
-:doc:`FAQs/Exclude_Repositories`
-
-:doc:`FAQs/IPTables_NAT_Rules`
-
-:doc:`FAQs/Local_User_Access/SSH_Keys`
-
-:doc:`FAQs/Network_Build`
-
-:doc:`FAQs/Override_Security_Module`
-
-:doc:`FAQs/Performing_One_Shot_Operations`
-
-:doc:`FAQs/Puppet_Server_NAT`
-
-:doc:`FAQs/Redundant_LDAP`
-
-:doc:`FAQs/SFTP_Restricted_Accounts`
-
-:doc:`FAQs/Ssh_keys`
+.. toctree::
+  :maxdepth: 1
+
+  FAQs/Centralized_Logging
+  FAQs/Changing_Puppet_Masters
+  FAQs/DVD_Build
+  FAQs/Exclude_Repositories
+  FAQs/IPTables_NAT_Rules
+  FAQs/Local_User_Access/SSH_Keys
+  FAQs/Network_Build
+  FAQs/Override_Security_Module
+  FAQs/Performing_One_Shot_Operations
+  FAQs/Puppet_Server_NAT
+  FAQs/Redundant_LDAP
+  FAQs/SFTP_Restricted_Accounts
+  FAQs/Ssh_keys
diff --git a/docs/user_guide/FAQs/Centralized_Logging.rst b/docs/user_guide/FAQs/Centralized_Logging.rst
@@ -15,7 +15,7 @@ the designated logging node.
 
 Code to Enable the Server Logging Examples
 
-.. code-block:: Ruby
+.. code-block:: ruby
 
           classes :
             - 'simp::rsyslog::stock'
@@ -29,6 +29,6 @@ the */etc/puppet/hieradata/simp\_def.yaml* file.
 
 Code to Enable the Client Logging Examples
 
-.. code-block:: Ruby
+.. code-block:: ruby
 
           log_server="fqdn.of.your.log.server"
diff --git a/docs/user_guide/FAQs/Changing_Puppet_Masters.rst b/docs/user_guide/FAQs/Changing_Puppet_Masters.rst
@@ -11,7 +11,7 @@ Enter the following changes into the */etc/puppet/puppet.conf* file.
 
 Code Changes on Client to Switch Puppet Masters
 
-.. code-block:: Ruby
+.. code-block:: ruby
 
             server = new.puppet.master.fqdn
             ca_server = new.puppet.master.fqdn

diff --git a/docs/user_guide/FAQs/IPTables_NAT_Rules.rst b/docs/user_guide/FAQs/IPTables_NAT_Rules.rst
@@ -17,7 +17,7 @@ The example below shows an IPtable NAT rule.
 
 Example of an IPtable NAT Rule
 
-.. code-block:: Ruby
+.. code-block:: ruby
 
               iptables::add_rules { "nat_global":
                  table => "nat",

diff --git a/docs/user_guide/FAQs/Local_User_Access/SSH_Keys.rst b/docs/user_guide/FAQs/Local_User_Access/SSH_Keys.rst
@@ -19,7 +19,7 @@ the generic variables included, as well as 2048-bit :term:`RSA` key generation.
 
 Code to Set Up a Local User SSH Connection Examples
 
-.. code-block:: Ruby
+.. code-block:: ruby
 
             class <CLASS NAME> {
               include "ssh"

diff --git a/docs/user_guide/FAQs/Override_Security_Module.rst b/docs/user_guide/FAQs/Override_Security_Module.rst
@@ -25,7 +25,7 @@ below in the *site.pp* or imported file.
 
 Break Out Security Settings from the Application
 
-.. code-block:: Ruby
+.. code-block:: ruby
 
             class base_config {
 
@@ -98,7 +98,7 @@ changed.
 
 Remove Security Module from Site Files
 
-.. code-block:: Bash
+.. code-block:: bash
 
             class site::security_override inherits sec::advanced
             {
@@ -132,7 +132,7 @@ file.
 
 Set All Security Default Site Settings Examples
 
-.. code-block:: Ruby
+.. code-block:: ruby
 
             node clientfqdn {
 

diff --git a/docs/user_guide/FAQs/Puppet_Server_NAT.rst b/docs/user_guide/FAQs/Puppet_Server_NAT.rst
@@ -13,7 +13,7 @@ The entries in *vars.pp* should look like the following example.
 
 Example Sample Entries in vars.pp
 
-.. code-block:: Ruby
+.. code-block:: ruby
 
            $puppet_server_hosts_mod = "puppet.$dns_domain|1.2.3.4 puppet2.$dns_domain|2.3.4.5"
            $puppet_servers = template('site/nat_ip_switch.erb')
@@ -30,7 +30,7 @@ portions of the content to meet the needs of the user environment.
 
 Source Create the nat\_ip\_switch.erb
 
-.. code-block:: Ruby
+.. code-block:: ruby
 
             <%
             # Edit this variable to provide the IP address mappings.

diff --git a/docs/user_guide/FAQs/Redundant_LDAP.rst b/docs/user_guide/FAQs/Redundant_LDAP.rst
@@ -18,7 +18,7 @@ using the *puppet\_servers.pp* file .
 
 Source Code for Using an OpenLDAP Server openldap
 
-.. code-block:: Ruby
+.. code-block:: ruby
 
             # These are some common variables.
             # See /etc/puppet/manifests/vars.pp for the stock version.
@@ -61,7 +61,7 @@ contact the master until they are successful.
 
 Source Code to Configure an LDAP Slave Node replication
 
-.. code-block:: Ruby
+.. code-block:: ruby
 
             class ldap_repl inherits ldap_common {
               include 'openldap::slapd::syncrepl'
@@ -97,7 +97,7 @@ server.
 
 Source Promoting a Slave Node LDAP
 
-.. code-block:: Ruby
+.. code-block:: ruby
 
             # Change the common ldap server variable to promote the slave node.
 
@@ -133,7 +133,7 @@ The example below shows the changes necessary to update the
 
 Update $ldap\_sync Information in LDAP Examples
 
-.. code-block:: Ruby
+.. code-block:: ruby
 
             dn: cn=LDAPSync,ou=People,dc=your,dc=domain
             changetype: modify

diff --git a/docs/user_guide/FAQs/SFTP_Restricted_Accounts.rst b/docs/user_guide/FAQs/SFTP_Restricted_Accounts.rst
@@ -11,7 +11,7 @@ Create a user account based on the following example.
 
 Create a User Account Examples
 
-.. code-block:: Ruby
+.. code-block:: ruby
 
             user { "foo":
               uid => <UID>,

diff --git a/docs/user_guide/Kerberos.rst b/docs/user_guide/Kerberos.rst
@@ -45,7 +45,7 @@ need to be made to the code.
 
 Code for Creating an Admin Principal Kerberos
 
-.. code-block:: Ruby
+.. code-block:: ruby
 
             krb5_acl{ "${::domain}_admin":
               principal       => "*/admin@${::domain}",

diff --git a/docs/user_guide/Logstash.rst b/docs/user_guide/Logstash.rst
@@ -147,7 +147,7 @@ Logstash Module Recommended SIMP Setup
 The following example manifest can be applied to a single host with a
 large /var volume and 4GB of memory.
 
-.. code-block:: Ruby
+.. code-block:: ruby
 
           ---
           # Add these settings to only your Logstash node.
@@ -185,7 +185,7 @@ In the case of the Elasticsearch node setup below, it may be better to
 use a group match to pull your Hiera settings. To do this, you should
 add the following to a file like /etc/puppet/manifests/nodegroups.pp
 
-.. code-block:: Ruby
+.. code-block:: ruby
 
           if $trusted['certname'] =~ /es\d+\.your\.domain/ {
             $hostgroup = 'elasticsearch'
@@ -203,7 +203,7 @@ Then, ensure that a file called 'elasticsearch.yaml' is present in the
 
 content.
 
-.. code-block:: Ruby
+.. code-block:: ruby
 
           ---
           # All nodes running elasticsearch in your cluster should use