Comment 15 for bug 1416572

Reviewed: https://review.openstack.org/162164
Committed: https://git.openstack.org/cgit/openstack/openstackdocstheme/commit/?id=35c795c05c2aa7b06722ab3860fd6907d8a8fc77
Submitter: Jenkins
Branch: master

commit 35c795c05c2aa7b06722ab3860fd6907d8a8fc77
Author: Bernd Bausch <email address hidden>
Date: Fri Mar 6 20:08:54 2015 +0900

    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