Sphinx openstackdocstheme doesn't style admonitions (note, warning, important) correctly

[Anne Gentle]

Here's the RST:

.. note:: Here's an example note.

Here's the output HTML:

<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Here&#8217;s an example note.</p>
</div>

Here's the HTML from the mockup at http://openstack-homepage.bitballoon.com/docs/book:

<div class="attention docs-note">
       <h3><i class="fa fa-check-circle"></i> Note</h3>
       <p>
        Ut aliquet sagittis egestas. <a href="#">Nam ullamcorper lobortis fringilla.</a> In velit sapien, facilisis tincidunt accumsan ac, congue sed nisl. Donec imperdiet, velit vel dignissim accumsan, enim nisi dapibus turpis, ut venenatis ante ante vel mauris. In et sollicitudin lacus. Sed fringilla eros lacus.
       </p>
      </div>

[Anne Gentle (annegentle)]

I think changing the CSS from attention docs-note class to admonition note class will do what's needed. There's still a problem with fa-check-circle not being copied to the right location on the build, so that also needs investigating.

[Anne Gentle (annegentle)]

I wonder if it's better to subclass with http://docutils.sourceforge.net/docs/howto/html-stylesheets.html

[Anne Gentle (annegentle)]

Partially fixed with https://github.com/annegentle/openstackdocstheme/blob/master/openstackdocstheme/theme/openstackdocs/static/css/combined.css

[Bernd Bausch (berndbausch)]

Here is a partial fix, which creates admonitions without the awesome font icons.

To fix the colours, rename

       admonition.docs-warning ---> admonition.warning
       admonition.docs-important ---> admonition.important

Which you already did for the note admonition, it would seem.

To make the text "Note", "Important", "Warning" come out bold, add a class

      .admonition-title { font-weight: 600; }

Essentially this overwrites the CSS classes admonition.warning, admonition.important and admonition-title from Sphinx's basic theme. Now I wonder if there is a reason why separate classes named something-docs exist - were they introduced for testing or do they have a purpose?

How to include the icons, I don't know yet. Perhaps with a "content" property in the admonition classes.

[Anne Gentle (annegentle)]

Yep, the classes named something-docs can definitely change, not a problem. It's the icons I also don't know how to get output.

[Anne Gentle (annegentle)]

One other idea, can we add a function to docs.js that adds the <i class="fa fa-check-circle"></i> for the <div class="admonition note">?

[Bernd Bausch (berndbausch)]

I don't think the Font Awesome icons can be added via CSS or Javascript, but that would be the best solution.
My solution now is an extension to Sphinx - that is, we don't touch the Sphinx code but create a small Python program in the root directory of our document tree. Will submit shortly.

[Bernd Bausch (berndbausch)]

Actually it could be done with Javascript, for example by looping over all HTML elements of the page and modifying those where all of the following is true:
1- they are paragraphs with class admonition-title
2- they are children of a div with class note/warning/important
This is not elegant, but only requires modification of the theme itself; no need for additional files and a modified conf.py in the document root.

[Anne Gentle (annegentle)]

Yes, the javascript solution is what I'm thinking would work. Worth a try anyway!

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.openstack.org/162164

[Bernd Bausch (berndbausch)]

Back to learning Javascript

[Bernd Bausch (berndbausch)]

A simpler solution for the Font Awesome icons is three short lines in docs.js. The following seems to work:

    $('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');

This way JSQuery adds the appropriate Font Awesome classes to an admonition-title paragraph inside an important, note and warning remark. We would still need a solution to add some space next to the icon; I don't know yet how to do that.

Given two very different solutions, which one is better? Assuming the additional space can be implemented as well, the JSQuery solution is simpler and easier to understand, and I believe that there is less dependency on Sphinx internals than in the case of the Sphinx extension.

[Anne Gentle (annegentle)]

Yep, I'd like to see the solution in docs.js -- easier to ship and track than an extra extension. Thank you, you are doing great work!

[Bernd Bausch (berndbausch)]

Implemented the jQuery solution in patch set 5 https://review.openstack.org/162164

[OpenStack Infra (hudson-openstack)]

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