Allow user to display/hide admonitions

Change-Id: I4ead7e3d7505b223737e63bdcefe2dfc2310b657

doc/source/_custom/admonition_selector.js

@@ -0,0 +1,58 @@
+/*
+  This function will search for all classes matching all IDs which are under
+  #admonition_selector element and display/hide their content.
+
+  State is saved in cookies so user doesn't lose his settings after page
+  reload or changing pages.
+
+  To make this feature work, you need to:
+  - add checkbox to _templates/layout.html file with proper ID
+  - in admonitions use proper class which matches above mentioned ID
+*/
+
+
+
+// after document is loaded
+$(document).ready(function() {
+
+    // for each checkbox in #admonition_selector do
+    $('#admonition_selector :checkbox').each(function() {
+
+      // check value of cookies and set state to the related element
+      if ($.cookie($(this).attr("id")) == "true") {
+        $(this).prop("checked", true);
+      } else if (($.cookie($(this).attr("id")) == "false")) {
+        $(this).prop("checked", false);
+      }
+
+      // show/hide elements after page loaded
+      toggle_admonition($(this).attr("id"));
+    });
+
+    // when user clicks on the checkbox, react
+    $('#admonition_selector :checkbox').change(function() {
+
+        // show/hide related elements
+        toggle_admonition($(this).attr("id"));
+
+        // save the state in the cookies
+        $.cookie($(this).attr("id"), $(this).is(':checked'), { path: '/' });
+    });
+});
+
+
+// function to show/hide elements based on checkbox state
+// checkbox has ID and it toggles elements having class named same way as the ID
+function toggle_admonition(admonition) {
+
+  // for each element having class as the checkbox's ID
+  $(".admonition." + admonition).each(function() {
+
+    // set show/hide
+    if($("#" + admonition).is(':checked')) {
+      $(this).show();
+    } else {
+      $(this).hide();
+    }
+  });
+}

doc/source/_custom/cookies.js

@@ -0,0 +1,117 @@
+/*!
+ * jQuery Cookie Plugin v1.4.1
+ * https://github.com/carhartl/jquery-cookie
+ *
+ * Copyright 2013 Klaus Hartl
+ * Released under the MIT license
+ */
+(function (factory) {
+  if (typeof define === 'function' && define.amd) {
+    // AMD
+    define(['jquery'], factory);
+  } else if (typeof exports === 'object') {
+    // CommonJS
+    factory(require('jquery'));
+  } else {
+    // Browser globals
+    factory(jQuery);
+  }
+}(function ($) {
+
+  var pluses = /\+/g;
+
+  function encode(s) {
+    return config.raw ? s : encodeURIComponent(s);
+  }
+
+  function decode(s) {
+    return config.raw ? s : decodeURIComponent(s);
+  }
+
+  function stringifyCookieValue(value) {
+    return encode(config.json ? JSON.stringify(value) : String(value));
+  }
+
+  function parseCookieValue(s) {
+    if (s.indexOf('"') === 0) {
+      // This is a quoted cookie as according to RFC2068, unescape...
+      s = s.slice(1, -1).replace(/\\"/g, '"').replace(/\\\\/g, '\\');
+    }
+
+    try {
+      // Replace server-side written pluses with spaces.
+      // If we can't decode the cookie, ignore it, it's unusable.
+      // If we can't parse the cookie, ignore it, it's unusable.
+      s = decodeURIComponent(s.replace(pluses, ' '));
+      return config.json ? JSON.parse(s) : s;
+    } catch(e) {}
+  }
+
+  function read(s, converter) {
+    var value = config.raw ? s : parseCookieValue(s);
+    return $.isFunction(converter) ? converter(value) : value;
+  }
+
+  var config = $.cookie = function (key, value, options) {
+
+    // Write
+
+    if (value !== undefined && !$.isFunction(value)) {
+      options = $.extend({}, config.defaults, options);
+
+      if (typeof options.expires === 'number') {
+        var days = options.expires, t = options.expires = new Date();
+        t.setTime(+t + days * 864e+5);
+      }
+
+      return (document.cookie = [
+        encode(key), '=', stringifyCookieValue(value),
+        options.expires ? '; expires=' + options.expires.toUTCString() : '', // use expires attribute, max-age is not supported by IE
+        options.path    ? '; path=' + options.path : '',
+        options.domain  ? '; domain=' + options.domain : '',
+        options.secure  ? '; secure' : ''
+      ].join(''));
+    }
+
+    // Read
+
+    var result = key ? undefined : {};
+
+    // To prevent the for loop in the first place assign an empty array
+    // in case there are no cookies at all. Also prevents odd result when
+    // calling $.cookie().
+    var cookies = document.cookie ? document.cookie.split('; ') : [];
+
+    for (var i = 0, l = cookies.length; i < l; i++) {
+      var parts = cookies[i].split('=');
+      var name = decode(parts.shift());
+      var cookie = parts.join('=');
+
+      if (key && key === name) {
+        // If second argument (value) is a function it's a converter...
+        result = read(cookie, value);
+        break;
+      }
+
+      // Prevent storing a cookie that we couldn't decode.
+      if (!key && (cookie = read(cookie)) !== undefined) {
+        result[name] = cookie;
+      }
+    }
+
+    return result;
+  };
+
+  config.defaults = {};
+
+  $.removeCookie = function (key, options) {
+    if ($.cookie(key) === undefined) {
+      return false;
+    }
+
+    // Must not alter options, thus extending a fresh object...
+    $.cookie(key, '', $.extend({}, options, { expires: -1 }));
+    return !$.cookie(key);
+  };
+
+}));

doc/source/_custom/custom.css

@@ -6,6 +6,14 @@
 
 
 /* LAYOUT */
+.wy-nav-side {
+  overflow: visible;
+}
+
+.wy-side-nav-search {
+  margin-bottom: 0;
+}
+
 .wy-nav-content-wrap {
   background: white;
 }
@@ -83,12 +91,74 @@ footer p {
 }
 
 /* tags */
-.rhel-tag {background: #fee;}
-.centos-tag {background: #fef;}
-.baremetal-tag {background: #eef;}
-.virt-tag {background: #efe;}
-.ceph-tag {background: #eff;}
+.rhel {background: #fee;}
+.centos {background: #fef;}
+.baremetal {background: #eef;}
+.virtual {background: #efe;}
+.ceph {background: #eff;}
 
+/* admonition selector */
+#admonition_selector {
+  color: white;
+  font-size: 85%;
+  line-height: 1.4;
+  background: #2980b9;
+  border-top: 1px solid rgba(255, 255, 255, 0.4);
+  margin-bottom: 0.5em;
+}
+
+.trigger {
+  display: block;
+  font-size: 110%;
+  color: rgba(255, 255, 255, 0.75);
+  line-height: 2.5;
+  position: relative;
+  cursor: pointer;
+  padding: 0 1.618em;
+}
+
+.trigger:after {
+  content: '';
+  display: block;
+  font-family: FontAwesome;
+  font-size: 70%;
+  position: absolute;
+  right: 1.618em;
+  top: 6px;
+}
+
+.trigger:hover {
+  color: white;
+}
+
+.content {
+  display: none;
+  border-top: 1px solid rgba(255, 255, 255, 0.1);
+  background: rgba(255, 255, 255, 0.1);
+  padding: 0.5em 1.618em;
+}
+
+.displayed .trigger:after {
+  content: '';
+}
+
+#admonition_selector .title {
+  color: rgba(255, 255, 255, 0.45);
+}
+
+#admonition_selector ul {
+  margin-bottom: 0.75em;
+}
+
+#admonition_selector ul li {
+  display: block;
+}
+
+#admonition_selector label {
+  display: inline;
+  color: inherit;
+  text-decoration: underline dotted;
+}
 
 /* LINKS */
 a.external:after {

doc/source/_custom/expandable.js

@@ -0,0 +1,32 @@
+$(document).ready(function() {
+
+  // for each trigger
+  $('.trigger').each(function() {
+
+    // check if cookie has value on true
+    if ($.cookie($(this).parent().prop('id')) == "true") {
+      // add displayed class and show the content
+      $(this).parent().addClass("displayed");
+      $(this).next('.content').show();
+
+    } else {
+      // remove displayed class and hide the content
+      $(this).parent().removeClass("displayed");
+      $(this).next('.content').hide();
+    }
+  });
+
+  // if user clicked trigger element
+  $('.trigger').click(function() {
+
+    // toggle parent's class and animate the content
+    $(this).parent().toggleClass('displayed');
+    $(this).next('.content').slideToggle("fast");
+
+    // save the state to cookies
+    var parent_id =
+    $.cookie($(this).parent().prop('id'),
+             $(this).parent().hasClass('displayed'),
+             { path: '/' });
+  });
+});

doc/source/_templates/layout.html

@@ -0,0 +1,33 @@
+{% extends "!layout.html" %}
+
+{% set script_files = script_files + ["_static/cookies.js"] %}
+{% set script_files = script_files + ["_static/expandable.js"] %}
+{% set script_files = script_files + ["_static/admonition_selector.js"] %}
+
+
+{% block menu %}
+  <div id="admonition_selector">
+    <span class="trigger">Limit Environment Specific Content</span>
+
+    <div class="content">
+      <span class="title">Operating Systems</span>
+      <ul>
+        <li><input type="checkbox" id="centos" checked="checked"><label for="centos" title="Step that should only be run when using CentOS.">CentOS</label></li>
+        <li><input type="checkbox" id="rhel" checked="checked"><label for="rhel" title="Step that should only be run when using RHEL.">RHEL</label></li>
+      </ul>
+
+      <span class="title">Environments</span>
+      <ul>
+        <li><input type="checkbox" id="baremetal" checked="checked"><label for="baremetal" title="Step that should only be run when deploying to baremetal.">Baremetal</label></li>
+        <li><input type="checkbox" id="virtual" checked="checked"><label for="virtual" title="Step that should only be run when deploying to virtual machines.">Virtual</label></li>
+      </ul>
+
+      <span class="title">Additional Overcloud Roles</span>
+      <ul>
+        <li><input type="checkbox" id="ceph" checked="checked"><label for="ceph" title="Step that should only be run when deploying Ceph for use by the Overcloud.">Ceph</label></li>
+      </ul>
+    </div>
+  </div>
+
+  {{ super() }}
+{% endblock %}

doc/source/build-images.rst

@@ -19,14 +19,14 @@ non-root user that was used to install the undercloud.
      ``instack-build-images``:
 
      .. admonition:: CentOS
-        :class: centos-tag
+        :class: centos
 
         ::
 
             export NODE_DIST=centos7
 
      .. admonition:: RHEL
-        :class: rhel-tag
+        :class: rhel
 
         ::
 
@@ -37,7 +37,7 @@ non-root user that was used to install the undercloud.
    .. only:: internal
 
       .. admonition:: RHEL
-         :class: rhel-tag
+         :class: rhel
 
          Download the RHEL 7.1 cloud image or copy it over from a different location,
          and define the needed environment variable for RHEL 7.1 prior to running
@@ -51,7 +51,7 @@ non-root user that was used to install the undercloud.
    .. only:: external
 
       .. admonition:: RHEL
-         :class: rhel-tag
+         :class: rhel
 
          Download the RHEL 7.1 cloud image or copy it over from a different location,
          for example:

doc/source/deploy-overcloud.rst

@@ -37,7 +37,7 @@ Ready-state configuration
 -------------------------
 
 .. admonition:: Baremetal
-   :class: baremetal-tag
+   :class: baremetal
 
    Some hardware has additional setup available, using its vendor-specific management
    interface.  See the :doc:`/vendor-specific` for details.
@@ -50,7 +50,7 @@ Create the necessary flavors::
     instack-ironic-deployment --setup-flavors
 
 .. admonition:: Baremetal
-   :class: baremetal-tag
+   :class: baremetal
 
    Copy the sample overcloudrc file and edit to reflect your environment. Then source this file::
 
@@ -60,7 +60,7 @@ Create the necessary flavors::
 Deploy the overcloud (default of 1 compute and 1 control):
 
 .. admonition:: Ceph
-   :class: ceph-tag
+   :class: ceph
 
    When deploying Ceph, specify the number of Ceph OSD nodes to be deployed
    with::

doc/source/environments/baremetal.rst

@@ -132,7 +132,7 @@ Setting Up The Undercloud Machine
 .. only:: external
 
    .. admonition:: RHEL
-      :class: rhel-tag
+      :class: rhel
 
        Register the host machine using Subscription Management::
 

doc/source/environments/virtual.rst

@@ -54,7 +54,7 @@ Preparing the Virtual Environment (Automated)
    .. only:: external
 
      .. admonition:: RHEL
-        :class: rhel-tag
+        :class: rhel
 
         Register the host machine using Subscription Management::
 
@@ -87,7 +87,7 @@ Preparing the Virtual Environment (Automated)
    .. only:: internal
 
       .. admonition:: RHEL
-         :class: rhel-tag
+         :class: rhel
 
           Enable rhos-release::
 
@@ -112,14 +112,14 @@ Preparing the Virtual Environment (Automated)
      ``instack-virt-setup``:
 
      .. admonition:: CentOS
-        :class: centos-tag
+        :class: centos
 
         ::
 
             export NODE_DIST=centos7
 
      .. admonition:: RHEL
-        :class: rhel-tag
+        :class: rhel
 
         ::
 
@@ -130,7 +130,7 @@ Preparing the Virtual Environment (Automated)
    .. only:: internal
 
      .. admonition:: RHEL
-        :class: rhel-tag
+        :class: rhel
 
         Download the RHEL 7.1 cloud image or copy it over from a different location,
         and define the needed environment variables for RHEL 7.1 prior to running
@@ -143,7 +143,7 @@ Preparing the Virtual Environment (Automated)
    .. only:: external
 
      .. admonition:: RHEL
-        :class: rhel-tag
+        :class: rhel
 
         Download the RHEL 7.1 cloud image or copy it over from a different location,
         for example:
@@ -161,7 +161,7 @@ Preparing the Virtual Environment (Automated)
                 rhel-7-server-optional-rpms rhel-7-server-openstack-6.0-rpms"
 
    .. admonition:: Ceph
-      :class: ceph-tag
+      :class: ceph
 
       To use Ceph you will need at least one additional virtual machine to be
       provisioned as a Ceph OSD; set the ``NODE_COUNT`` variable to 3, from a

doc/source/index.rst

@@ -26,32 +26,32 @@ Documentation Conventions
 =========================
 
 Some steps in the following instructions only apply to certain environments,
-such as deployments to real baremetal and deployments using RHEL.  These
+such as deployments to real baremetal and deployments using RHEL. These
 steps are marked as follows:
 
 .. admonition:: RHEL
-   :class: rhel-tag
+   :class: rhel
 
    Step that should only be run when using RHEL
 
 .. admonition:: CentOS
-   :class: centos-tag
+   :class: centos
 
    Step that should only be run when using CentOS
 
 
 .. admonition:: Baremetal
-   :class: baremetal-tag
+   :class: baremetal
 
    Step that should only be run when deploying to baremetal
 
-.. admonition:: Virt
-   :class: virt-tag
+.. admonition:: Virtual
+   :class: virtual
 
    Step that should only be run when deploying to virtual machines
 
 .. admonition:: Ceph
-   :class: ceph-tag
+   :class: ceph
 
    Step that should only be run when deploying Ceph for use by the Overcloud
 

doc/source/install-undercloud.rst

@@ -4,13 +4,13 @@ Installing the Undercloud
 Make sure you are logged in as a non-root user (such as the stack user) on the
 node on which you want to install the undercloud.
 
-.. admonition:: Virt
-   :class: virt-tag
+.. admonition:: Virtual
+   :class: virtual
 
    This node will be a VM called *instack* and you can use the stack user.
 
 .. admonition:: Baremetal
-   :class: baremetal-tag
+   :class: baremetal
 
    This will be the host you selected for the Undercloud while preparing the environment.
 
@@ -19,7 +19,7 @@ node on which you want to install the undercloud.
    .. only:: internal
 
       .. admonition:: RHEL
-         :class: rhel-tag
+         :class: rhel
 
           Enable rhos-release::
 
@@ -41,7 +41,7 @@ node on which you want to install the undercloud.
         127.0.0.1   myhost.mydomain
 
   .. admonition:: Baremetal
-     :class: baremetal-tag
+     :class: baremetal
 
      Copy in the sample answers file and edit it to reflect your environment::