[ADD] extensions: icon_role font awesome

X-original-commit: 1039a0b

content/contributing/documentation/rst_cheat_sheet.rst

@@ -211,6 +211,24 @@ Use the `command` markup to highlight a command.
           Run the command :command:`make clean html` to delete existing built files and build the
           documentation to HTML.
 
+.. _contributing/markups/icons:
+
+Icons
+-----
+
+Use the `icon` markup to add a class name of an icon. The icon set used is *Font Awesome*. It is
+recommended to accompany an icon with a :ref:`contributing/markups/guilabel` as a descriptor,
+however, it is not mandatory.
+
+.. list-table::
+   :class: o-showcase-table
+
+   * - The graph view is represented by the :icon:`fa-bar-chart` :guilabel:`(bar chart)` icon.
+
+   * - .. code-block:: text
+
+          The graph view is represented by the :icon:`fa-bar-chart` :guilabel:`(bar chart)` icon.
+
 .. _contributing/lists:
 
 Lists

extensions/odoo_theme/__init__.py

@@ -1,4 +1,5 @@
 from docutils import nodes
+from docutils.parsers.rst import roles
 from sphinx import addnodes
 from sphinx.environment.adapters import toctree
 
@@ -16,6 +17,8 @@ def setup(app):
     app.add_js_file('js/page_toc.js')
     app.add_js_file('js/switchers.js')
 
+    roles.register_canonical_role('icon', icon_role)
+
     return {
         'parallel_read_safe': True,
         'parallel_write_safe': True
@@ -107,3 +110,17 @@ def _set_docname_as_class(_reference_node, _node_docname):
     if resolved_toc:  # `resolve` returns None if the depth of the TOC to resolve is too high
         _update_toctree_nodes(resolved_toc)
     return resolved_toc
+
+
+def icon_role(name, rawtext, text, lineno, inliner, options=None, content=None):
+    """ Implement an `icon` role for Odoo and Font Awesome icons. """
+    for icon_class in text.split():
+        if not icon_class.startswith('fa-'):
+            report_error = inliner.reporter.error(
+                f"'{icon_class}' is not a valid icon formatting class.", lineno=lineno
+            )
+            error_node = inliner.problematic(rawtext, rawtext, report_error)
+            return [error_node], [report_error]
+    icon_html = f'<i class="{text}"></i>'
+    node = nodes.raw('', icon_html, format='html')
+    return [node], []