Font Awesome role for sphinx documentation

fontawesome.py

# Place in docs/_ext
# 
# Add to conf.py:
#   sys.path.append(os.path.abspath("./_ext")
#   extensions = [
#       # ...
#       'fontawesome',
#   ]
#

from docutils.nodes import emphasis
from docutils.parsers.rst.roles import set_classes


def fa(role, rawtext, text, lineno, inliner, options={}, content=[]):
    """Adds an `:fa:` role to docs to insert an icon from Font Awesome.

    The extension assumes that fontawesome assets are already included in the
    document build, for example by using the `sphinx_rtd_theme` theme, which
    uses Font Awesome as well.
    """
    classes = ["fa"]
    for x in text.split(","):
        classes.append('fa-{}'.format(x))

    options.update({'classes': classes})
    set_classes(options)
    node = emphasis(**options)
    return [node], []


def setup(app):
    app.add_role('fa', fa)
    return {'version': "0.1"}