Rendering admonitions with Font Awesome icons

For documentation based on restructured text (RST), notes, warnings and
important remarks, in RST jargon "admonitions", need to be rendered
differently than Sphinx does it by default.

Specifically:
- admonition boxes require certain colour
- box titles "Note", "Warning", "Important" or their i18n equivalents
  must be bold,
- Font Awesome icons decorate the boxes

Colour and Boldness are easily fixed in the combined.css file.
Icons are added by jQuery code.

Example: this RST code

    .. note:: some text here

is rendered by Sphinx as:

    <div class="admonition note">
    <p class="first admonition-title">Note</p>
    <p class="last">some text here</p>
    </div>

To add the appropriate Font Awesome icon, the second line needs to be:

    <p class="fa fa-check-circle first admonition-title"> Note</p>

This is achieved by jQuery code in docs.js that adds the FA classes and
puts a space in front of the title text.

As a side effect of adding the FA classes, the admonition title font has
become smaller. I have not found out what causes this, but it doesn't look
too bad, so I keep it.

An alternative to the jQuery method is writing a Sphinx extension to
modify Sphinx output. While this is a more elegant solution (OK, elegance
is in the eye of the beholder), it requires shipping additional code, is
more difficult to understand and relies on Sphinx features that are not that
well documented. Thus we abandoned this solution. In case someone wants to
unearth it, it's available in patch set 4.

Change-Id: I7f8bffd19ec2f8695cac09bc577aa6bac132dc20
Closes-Bug: #1416572

doc/source/conf.py

@@ -30,7 +30,6 @@ import openstackdocstheme
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = []
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

openstackdocstheme/theme/openstackdocs/css.html

@@ -1,16 +1,18 @@
     <!-- Bootstrap Core CSS -->
     <link href="{{pathto('_static/css/bootstrap.min.css', 1)}}" rel="stylesheet">
 
-    <!-- Custom CSS -->
-    <link href="{{pathto('_static/css/combined.css', 1)}}" rel="stylesheet">
-    <link href="{{pathto('_static/css/styles.css', 1)}}" rel="stylesheet">
-
 
     <!-- Fonts -->
     <!--<link href="font-awesome.min.css" rel="stylesheet">-->
     <link href="http://maxcdn.bootstrapcdn.com/font-awesome/4.2.0/css/font-awesome.min.css" rel="stylesheet">
     <link href='http://fonts.googleapis.com/css?family=Open+Sans:300,400,700' rel='stylesheet' type='text/css'>
 
+	<!-- BB: theme style sheets moved here so that theme rules aren't 
+	     overridden by awesome rules. Should they go after the scripts below? -->
+    <!-- Custom CSS -->
+    <link href="{{pathto('_static/css/combined.css', 1)}}" rel="stylesheet">
+    <link href="{{pathto('_static/css/styles.css', 1)}}" rel="stylesheet">
+
     <!-- HTML5 Shim and Respond.js IE8 support of HTML5 elements and media queries -->
     <!-- WARNING: Respond.js doesn't work if you view the page via file:// -->
     <!--[if lt IE 9]>

openstackdocstheme/theme/openstackdocs/static/css/combined.css

@@ -318,11 +318,13 @@ input.action {
   color: #33730a;
   text-decoration: underline; }
 
+/* BB: Removed because it looks ugly
 .note p {
   margin-left: 8px;
   padding: 10px;
   margin-bottom: 0px;
   border-bottom: 1px solid #b5c8a8; }
+*/
 
 a#CitrixVideo {
   display: block;
@@ -4291,34 +4293,42 @@ pre .cl {
 .admonition.note a {
   color: #2A4E68; }
 
-.admonition.docs-important {
+/* BB: The following eight rules, four "important" and four "warning",
+   originally had names "docs-important" and "docs-warning" */
+
+.admonition.important {
   background: #FEFFBE;
   border-color: #D7AA16;
   color: #D7AA16; }
 
-.admonition.docs-important a {
+.admonition.important a {
   color: #e8be15; }
 
-.admonition.docs-important h3 {
+.admonition.important h3 {
   color: #e8be15; }
 
-.admonition.docs-important h3 i {
+.admonition.important h3 i {
   color: #e8be15; }
 
-.admonition.docs-warning {
+.admonition.warning {
   background: #FED3D9;
   border-color: #DA422F;
   color: #DA422F; }
 
-.admonition.docs-warning h3 {
+.admonition.warning h3 {
   color: #DA422F; }
 
-.admonition.docs-warning h3 i {
+.admonition.warning h3 i {
   color: #DA422F; }
 
-.admonition.docs-warning a {
+.admonition.warning a {
   color: #DA422F; }
 
+/* BB: added the adminition-title rule to bolden the adminition title */
+.admonition-title {
+  font-weight: 600;
+}
+
 .docs-tags {
   width: 100%;
   margin-bottom: 30px; }

openstackdocstheme/theme/openstackdocs/static/js/docs.js

@@ -86,7 +86,33 @@ $.getJSON('common/js/doc-characters.json', function(data) {
   $('<p>' + item.caption + '<strong>OpenStack Operator</strong></p>').appendTo('#superuser-img');
 });
 
+/* BB 150310
+   openstackdocstheme provides three types of admonitions, important, note 
+   and warning. We decorate their title paragraphs with Font Awesome icons
+   by adding the appropriate FA classes.                               */
 
+$('div.important > p.admonition-title').addClass('fa fa-info-circle');
+$('div.note > p.admonition-title').addClass('fa fa-check-circle');
+$('div.warning > p.admonition-title').addClass('fa fa-exclamation-triangle');
 
+/* BB 150310
+   We also insert a space between the icon and the admonition title 
+   ("Note", "Warning", "Important" or their i18n equivalents).    
 
+   This could be done with a single clause $('p.admonition-title')...., 
+   affecting all types of admonitions. I play it safe here and explicitly 
+   work on the three openstackdocstheme admonitions.                           
+   
+   The first parameter of the text() callback is not needed here (it's 
+   the index of the HTML element that we are modifying)                 */
+
+$('div.important > p.admonition-title').text(function(ignored_para,original) {
+    return " "+original
+});
+$('div.note > p.admonition-title').text(function(ignored_para,original) {
+    return " "+original
+});
+$('div.warning > p.admonition-title').text(function(ignored_para,original) {
+    return " "+original
+});