Add inline icons roles (opticon and fontawesome) (#26)

Author: chrisjsewell

docs/index.rst

@@ -2,11 +2,6 @@
 sphinx-panels
 =============
 
-.. contents::
-    :local:
-    :depth: 2
-
-
 A sphinx extension for creating panels in a grid layout or as drop-downs.
 
 - The ``panels`` directive creates panels of content in a grid layout, utilising both the bootstrap 4
@@ -15,6 +10,7 @@ A sphinx extension for creating panels in a grid layout or as drop-downs.
 - The ``link-button`` directive creates a click-able button, linking to a URL or reference,
   and can also be used to make an entire panel click-able.
 - The ``dropdown`` directive creates toggle-able content.
+- ``opticon`` and ``fa`` roles allow for inline icons to be added.
 
 .. code-block:: rst
 
@@ -28,7 +24,7 @@ A sphinx extension for creating panels in a grid layout or as drop-downs.
 
         ---
 
-        .. dropdown:: Bottom-left panel
+        .. dropdown:: :fa:`eye,mr-1` Bottom-left panel
 
             Hidden content
 
@@ -48,7 +44,7 @@ A sphinx extension for creating panels in a grid layout or as drop-downs.
 
     ---
 
-    .. dropdown:: Bottom-left panel
+    .. dropdown:: :fa:`eye,mr-1` Bottom-left panel
 
         Hidden content
 
@@ -58,8 +54,8 @@ A sphinx extension for creating panels in a grid layout or as drop-downs.
         :text: Clickable Panel
         :classes: stretched-link
 
-.. dropdown:: See this documentation in other themes...
-    :title: bg-info text-white
+.. dropdown:: :fa:`eye,mr-1` See this documentation in other themes
+    :title: text-info font-weight-bold
 
     Click the links to see the documentation built with:
 
@@ -69,11 +65,20 @@ A sphinx extension for creating panels in a grid layout or as drop-downs.
     - `sphinx-book-theme <https://sphinx-panels.readthedocs.io/en/sphinx-book-theme/>`_
 
 
-.. tip::
+.. panels::
+    :column: col-lg-12 p-0
+    :header: text-secondary font-weight-bold
+
+    :fa:`arrows-alt,mr-1` Adaptive Sizing
+
+    ^^^
 
     Try shrinking the size of this window,
-    to see how the panels realign to compensate for small screens.
+    to see how the panels above realign to compensate for small screens.
 
+.. contents::
+    :local:
+    :depth: 2
 
 Installation
 ============
@@ -564,6 +569,45 @@ Adding the ``animate`` option will trigger an animation when the content of the
 
     Current available inputs: ``fade-in``, ``fade-in-slide-down``
 
+Inline Icons
+============
+
+Inline icons can be added to your text from either the
+`GitHub octicon <https://octicons-git-v2.primer.now.sh/octicons/>`_ or
+`FontAwesome <https://fontawesome.com/icons?d=gallery&m=free>`_ libraries.
+
+====================================================== ===============================================
+rST                                                    Output
+====================================================== ===============================================
+``:opticon:`report```                                  :opticon:`report`
+``:opticon:`x-circle,text-white bg-danger,size=24```   :opticon:`x-circle,text-white bg-danger,size=24`
+``:fa:`save```                                         :fa:`save`
+``:fa:`spinner,text-white bg-primary fa-2x,style=fa``` :fa:`spinner,text-white bg-primary fa-2x,style=fa`
+====================================================== ===============================================
+
+Note that the theme you are using does not already include the FontAwesome CSS,
+it should be loaded in your ``conf.py``,
+with the `html_css_files <https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_css_files>`_ option, e.g.:
+
+.. code-block:: python
+
+    html_css_files = ["https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css"]
+
+By default, icons will only be output in HTML formats.
+But if you want fontawesome icons to be output on LaTeX, using the `fontawesome package <https://ctan.org/pkg/fontawesome>`_,
+you can add to your ``conf.py``:
+
+.. code-block:: python
+
+    panels_add_fontawesome_latex = True
+
+Additional classes can be added after a comma delimiter.
+Also the size (16px or 24px) can be set for opticons, and the style/prefix for fontawesome (version 5).
+
+.. seealso::
+
+    https://www.w3schools.com/icons/fontawesome_icons_intro.asp
+
 Div Directive
 =============
 

setup.py

@@ -31,6 +31,7 @@
             "css/bs-buttons.css",
             "css/panels-bootstrap.min.css",
             "css/sphinx-dropdown.css",
+            "data/opticons.json",
         ]
     },
     install_requires=["docutils", "sphinx"],

sphinx_panels/__init__.py

@@ -7,6 +7,7 @@
 from .button import setup_link_button
 from .dropdown import setup_dropdown
 from .panels import setup_panels
+from .icons import setup_icons
 
 __version__ = "0.4.0"
 
@@ -77,6 +78,7 @@ def setup(app):
     setup_panels(app)
     setup_link_button(app)
     setup_dropdown(app)
+    setup_icons(app)
 
     return {
         "version": __version__,

sphinx_panels/css/sphinx-dropdown.css

@@ -1,3 +1,8 @@
+.octicon {
+    display: inline-block;
+    vertical-align: text-top;
+    fill: currentColor;
+}
 details.dropdown .summary-title {
     -webkit-user-select: none;
        -moz-user-select: none;
@@ -24,39 +29,39 @@ details.dropdown summary::-webkit-details-marker {
 details.dropdown summary:focus {
     outline: none;
 }
-details.dropdown summary:hover .summary-chevron-up svg,
-details.dropdown summary:hover .summary-chevron-down svg {
+details.dropdown summary:hover .summary-up svg,
+details.dropdown summary:hover .summary-down svg {
     opacity: 1;
 }
-details.dropdown .summary-chevron-up svg,
-details.dropdown .summary-chevron-down svg {
+details.dropdown .summary-up svg,
+details.dropdown .summary-down svg {
     opacity: 0.6;
 }
-details.dropdown .summary-chevron-up,
-details.dropdown .summary-chevron-down {
+details.dropdown .summary-up,
+details.dropdown .summary-down {
     pointer-events: none;
     position: absolute;
     top: 0.75em;
     right: 1em;
 }
-details.dropdown .summary-chevron-up svg,
-details.dropdown .summary-chevron-down svg {
+details.dropdown .summary-up svg,
+details.dropdown .summary-down svg {
     display: block;
 }
-details.dropdown[open] .summary-chevron-up{
+details.dropdown[open] .summary-down{
     visibility: hidden;
     /* z-index: -1; */
 }
-details.dropdown:not([open]) .summary-chevron-down{
+details.dropdown:not([open]) .summary-up{
     visibility: hidden;
     /* z-index: -1; */
 }
 
 /* Ellipsis added when no title */
-details.dropdown summary .ellipsis {
+details.dropdown summary .octicon.no-title {
     vertical-align: middle;
 }
-details.dropdown[open] summary .ellipsis{
+details.dropdown[open] summary .octicon.no-title{
     visibility: hidden;
 }
 

sphinx_panels/data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 GitHub Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sphinx_panels/data/opticons.json

@@ -6,6 +6,8 @@
 from sphinx.transforms.post_transforms import SphinxPostTransform
 from sphinx.util.nodes import NodeMatcher
 
+from .icons import get_opticon
+
 
 def setup_dropdown(app):
     app.add_node(dropdown_main, html=(visit_dropdown_main, depart_dropdown_main))
@@ -50,7 +52,6 @@ class DropdownDirective(SphinxDirective):
         "title": directives.unchanged,
         "body": directives.unchanged,
         "open": directives.flag,
-        "marker-color": directives.unchanged,
         "name": directives.unchanged,
         "animate": lambda a: directives.choice(a, ("fade-in", "fade-in-slide-down")),
     }
@@ -83,7 +84,6 @@ def run(self):
 
         container = nodes.container(
             "",
-            marker_color=self.options.get("marker-color", "currentColor"),
             opened="open" in self.options,
             type="dropdown",
             has_title=len(self.arguments) > 0,
@@ -98,18 +98,10 @@ def run(self):
         return [container]
 
 
-CHEVRON = """\
-<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24"
-    viewBox="0 0 24 24" fill="none"
-    stroke="{color}" stroke-width="2"stroke-linecap="round" stroke-linejoin="round"
->
-<polyline points="{points}"></polyline>
-</svg>"""
-
-ELLIPSIS = """\
+KEBAB = """\
 <svg viewBox="0 0 36 24" width="36" height="16" xmlns="http://www.w3.org/2000/svg"
-    data-icon="ui-components:ellipses" class="ellipsis">
-  <g xmlns="http://www.w3.org/2000/svg" class="jp-icon3" fill="currentColor">
+    class="octicon no-title" aria-hidden="true">
+  <g xmlns="http://www.w3.org/2000/svg" class="jp-icon3">
     <circle cx="0" cy="12" r="6"></circle>
     <circle cx="18" cy="12" r="6"></circle>
     <circle cx="36" cy="12" r="6"></circle>
@@ -128,30 +120,18 @@ def run(self):
             open_marker = nodes.container(
                 "",
                 nodes.raw(
-                    "",
-                    nodes.Text(
-                        CHEVRON.format(
-                            color=node["marker_color"], points="18 15 12 9 6 15"
-                        )
-                    ),
-                    format="html",
+                    "", nodes.Text(get_opticon("chevron-up", size=24)), format="html"
                 ),
                 is_div=True,
-                classes=["summary-chevron-down"],
+                classes=["summary-up"],
             )
             closed_marker = nodes.container(
                 "",
                 nodes.raw(
-                    "",
-                    nodes.Text(
-                        CHEVRON.format(
-                            color=node["marker_color"], points="6 9 12 15 18 9"
-                        )
-                    ),
-                    format="html",
+                    "", nodes.Text(get_opticon("chevron-down", size=24)), format="html"
                 ),
                 is_div=True,
-                classes=["summary-chevron-up"],
+                classes=["summary-down"],
             )
 
             newnode = dropdown_main(
@@ -163,7 +143,18 @@ def run(self):
                 title_children = node[0]
                 body_children = node[1:]
             else:
-                title_children = [nodes.raw("...", nodes.Text(ELLIPSIS), format="html")]
+                title_children = [
+                    nodes.raw(
+                        "...",
+                        nodes.Text(
+                            KEBAB
+                            # Note the custom opticon here has thicker dots
+                            # get_opticon("kebab-horizontal", classes="no-title",
+                            # size=24)
+                        ),
+                        format="html",
+                    )
+                ]
                 body_children = node
 
             newnode += dropdown_title(