ENH: add icon_links option for custom navbar icons (with docs and pyp…

…i example) (#293)
pydata · Mar 9, 2021 · e32af5f · e32af5f
1 parent 93b5115
commit e32af5f
Show file tree

Hide file tree

Showing 11 changed files with 155 additions and 51 deletions.
diff --git a/docs/conf.py b/docs/conf.py
@@ -68,6 +68,13 @@
     ],
     "github_url": "https://github.com/pandas-dev/pydata-sphinx-theme",
     "twitter_url": "https://twitter.com/pandas_dev",
+    "icon_links": [
+        {
+            "name": "PyPI",
+            "url": "https://pypi.org/project/pydata-sphinx-theme",
+            "icon": "fas fa-box",
+        }
+    ],
     "use_edit_page_button": True,
     "show_toc_level": 1,
     # "navbar_align": "right",  # For testing that the navbar items align properly

diff --git a/docs/user_guide/configuring.rst b/docs/user_guide/configuring.rst
@@ -19,7 +19,7 @@ doc path's _static folder, and use the following configuration:
 
    html_logo = "_static/logo.png"
 
-The logo links to ``master_doc`` (usually the first page of your documentation) by default. 
+The logo links to ``master_doc`` (usually the first page of your documentation) by default.
 If you'd like it to link to another page or use an external link instead, use the following configuration:
 
 .. code:: python
@@ -29,20 +29,80 @@ If you'd like it to link to another page or use an external link instead, use th
    }
 
 
-Configure social media buttons
-==============================
+Configure icon links
+====================
 
-If you'd like social media buttons to show up to the right of your nav bar, use the
+If you'd like icon links to show up to the right of your main navigation bar, use the
 following configuration:
 
 .. code:: python
 
    html_theme_options = {
-     "github_url": "https://github.com/<your-org>/<your-repo>",
-     "gitlab_url": "https://gitlab.com/<your-org>/<your-repo>",
-     "twitter_url": "https://twitter.com/<your-handle>",
+       ...
+       "icon_links": [
+           {
+               "name": "GitHub",
+               "url": "https://github.com/<your-org>/<your-repo>",
+               "icon": "fab fa-github-square",
+           },
+           {
+               "name": "GitLab",
+               "url": "https://gitlab.com/<your-org>/<your-repo>",
+               "icon": "fab fa-gitlab",
+           },
+           {
+               "name": "Twitter",
+               "url": "https://twitter.com/<your-handle>",
+               "icon": "fab fa-twitter-square",
+           },
+       ],
+       ...
+   }
+
+
+The value of ``icon`` can be any full
+`FontAwesome 5 Free <https://fontawesome.com/icons?d=gallery&m=free>`__ icon.
+In addition to the main icon class, e.g. ``fa-cat``, the "style" class must
+also be provided e.g. `fab` for *branding*, or `fas` for *solid*.
+
+
+.. Hint::
+
+   To get custom colors like "Twitter blue", use the following in your CSS,
+   e.g. ``custom.css``:
+
+   .. code:: css
+
+      i.fa-twitter-square:before {
+         color: #55acee;
+      }
+
+   This has already been added for the brands that have *shortcuts*.
+
+The below are shortcuts for commonly-used services, but may be removed in a future
+release in favor of ``icon_links``:
+
+.. code:: python
+
+   html_theme_options = {
+       ...
+       "github_url": "https://github.com/<your-org>/<your-repo>",
+       "gitlab_url": "https://gitlab.com/<your-org>/<your-repo>",
+       "twitter_url": "https://twitter.com/<your-handle>",
+       ...
    }
 
+Additionally, the screen-reader accessible label for this menu can be configured:
+
+.. code:: python
+
+   html_theme_options = {
+       ...
+       "icon_links_label": "Quick Links",
+       ...
+   }
+
+
 Adding external links to your nav bar
 =====================================
 

diff --git a/pydata_sphinx_theme/docs-navbar.html b/pydata_sphinx_theme/docs-navbar.html
@@ -1,4 +1,3 @@
-
 <div class="container-xl">
 
 
@@ -37,33 +36,12 @@
         {% endfor %}
       </ul>
 
-
       {% if theme_search_bar_position == 'navbar' %}
         {%- include "search-field.html" %}
       {% endif %}
 
-      <ul class="navbar-nav">
-        {% if theme_github_url | length > 2 %}
-          <li class="nav-item">
-            <a class="nav-link" href="{{ theme_github_url }}" target="_blank" rel="noopener">
-              <span><i class="fab fa-github-square"></i></span>
-            </a>
-          </li>
-        {% endif %}
-        {% if theme_gitlab_url | length > 2 %}
-          <li class="nav-item">
-            <a class="nav-link" href="{{ theme_gitlab_url }}" target="_blank" rel="noopener">
-              <span><i class="fab fa-gitlab"></i></span>
-            </a>
-          </li>
-        {% endif %}
-        {% if theme_twitter_url | length > 2 %}
-          <li class="nav-item">
-            <a class="nav-link" href="{{ theme_twitter_url }}" target="_blank" rel="noopener">
-              <span><i class="fab fa-twitter-square"></i></span>
-            </a>
-          </li>
-        {% endif %}
-      </ul>
+      {%- block icon_links -%}
+      {%- include "icon-links.html" with context -%}
+      {%- endblock %}
     </div>
 </div>
diff --git a/pydata_sphinx_theme/icon-links.html b/pydata_sphinx_theme/icon-links.html
@@ -0,0 +1,21 @@
+{%- macro icon_link_nav_item(url, icon, name) -%}
+  {%- if url | length > 2 %}
+        <li class="nav-item">
+          <a class="nav-link" href="{{ url }}" rel="noopener" target="_blank" title="{{ _(name) }}">
+            <span><i class="{{ icon }}"></i></span>
+            <label class="sr-only">{{ _(name) }}</label>
+          </a>
+        </li>
+  {%- endif -%}
+{%- endmacro -%}
+
+      <ul id="navbar-icon-links" class="navbar-nav" aria-label="{{ _(theme_icon_links_label) }}">
+        {%- block icon_link_shortcuts -%}
+        {{ icon_link_nav_item(theme_github_url, "fab fa-github-square", "GitHub") -}}
+        {{ icon_link_nav_item(theme_gitlab_url, "fab fa-gitlab", "GitLab") -}}
+        {{ icon_link_nav_item(theme_twitter_url, "fab fa-twitter-square", "Twitter") -}}
+        {% endblock -%}
+        {%- for icon_link in theme_icon_links -%}
+        {{ icon_link_nav_item(icon_link["url"], icon_link["icon"], icon_link["name"]) -}}
+        {%- endfor %}
+      </ul>
diff --git a/...ndex.0e366ba14472447708f75ccb7d8f24a3.css → ...ndex.4ea0a4617f49cfd39b5b9e9540ffc872.css b/...ndex.0e366ba14472447708f75ccb7d8f24a3.css → ...ndex.4ea0a4617f49cfd39b5b9e9540ffc872.css
diff --git a/...e/static/js/index.9ab83e9ee01d4093105a.js → ...e/static/js/index.bf572f7d6dfb3e591c72.js b/...e/static/js/index.9ab83e9ee01d4093105a.js → ...e/static/js/index.bf572f7d6dfb3e591c72.js
diff --git a/pydata_sphinx_theme/static/webpack-macros.html b/pydata_sphinx_theme/static/webpack-macros.html
@@ -17,13 +17,13 @@
 
 {% macro head_pre_bootstrap() %}
   <link href="{{ pathto('_static/css/theme.css', 1) }}" rel="stylesheet" />
-  <link href="{{ pathto('_static/css/index.0e366ba14472447708f75ccb7d8f24a3.css', 1) }}" rel="stylesheet" />
+  <link href="{{ pathto('_static/css/index.4ea0a4617f49cfd39b5b9e9540ffc872.css', 1) }}" rel="stylesheet" />
 {% endmacro %}
 
 {% macro head_js_preload() %}
-  <link rel="preload" as="script" href="{{ pathto('_static/js/index.9ab83e9ee01d4093105a.js', 1) }}">
+  <link rel="preload" as="script" href="{{ pathto('_static/js/index.bf572f7d6dfb3e591c72.js', 1) }}">
 {% endmacro %}
 
 {% macro body_post() %}
-  <script src="{{ pathto('_static/js/index.9ab83e9ee01d4093105a.js', 1) }}"></script>
+  <script src="{{ pathto('_static/js/index.bf572f7d6dfb3e591c72.js', 1) }}"></script>
 {% endmacro %}
diff --git a/pydata_sphinx_theme/theme.conf b/pydata_sphinx_theme/theme.conf
@@ -10,7 +10,10 @@ use_edit_page_button = False
 external_links =
 logo_link =
 github_url =
+gitlab_url =
 twitter_url =
+icon_links_label = Icon Links
+icon_links =
 google_analytics_id =
 show_prev_next = True
 search_bar_text = Search the docs ...

diff --git a/src/scss/index.scss b/src/scss/index.scss
@@ -408,25 +408,36 @@ table.field-list {
   color: #e83e8c;
 }
 
-/* Social media buttons */
-
-i {
-  &.fab {
-    vertical-align: middle;
-    font-style: normal;
-    font-size: 1.5rem;
-    line-height: 1.25;
-  }
+/* Icon Links */
 
-  &.fa-github-square:before {
-    color: #333;
-  }
+#navbar-icon-links {
+  i {
+    &.fa,
+    &.fab,
+    &.far,
+    &.fas{
+      vertical-align: middle;
+      font-style: normal;
+      font-size: 1.5rem;
+      line-height: 1.25;
+    }
+
+    /* Social media buttons */
+    &.fa-github-square:before {
+      color: #333;
+    }
+
+    &.fa-twitter-square:before {
+      color: #55acee;
+    }
 
-  &.fa-twitter-square:before {
-    color: #55acee;
+    &.fa-gitlab:before {
+      color: #548
+    }
   }
 }
 
+
 /* TOC section headers */
 
 .tocsection {

diff --git a/tests/test_build/icon_links.html b/tests/test_build/icon_links.html
@@ -0,0 +1,24 @@
+<ul aria-label="Quick Links" class="navbar-nav" id="navbar-icon-links">
+ <li class="nav-item">
+  <a class="nav-link" href="x://y/z" rel="noopener" target="_blank" title="GitHub">
+   <span>
+    <i class="fab fa-github-square">
+    </i>
+   </span>
+   <label class="sr-only">
+    GitHub
+   </label>
+  </a>
+ </li>
+ <li class="nav-item">
+  <a class="nav-link" href="x://y/z" rel="noopener" target="_blank" title="Xyz">
+   <span>
+    <i class="fax fa-xyz">
+    </i>
+   </span>
+   <label class="sr-only">
+    Xyz
+   </label>
+  </a>
+ </li>
+</ul>
diff --git a/tests/test_build/navbar_ix.html b/tests/test_build/navbar_ix.html
@@ -16,6 +16,6 @@
    </a>
   </li>
  </ul>
- <ul class="navbar-nav">
+ <ul aria-label="Icon Links" class="navbar-nav" id="navbar-icon-links">
  </ul>
 </div>