Move icons to header in docs

[RemDelaporteMathurin]

Proposed changes

Following the modifications proposed in executablebooks/sphinx-book-theme#833 by @danilopeixoto we can finally move the icons to the header as we initially wanted.

@danilopeixoto, do you know by any chance if there is a way to combine this and have some icons in the header and others in the sidebar?

Types of changes

What types of changes does your code introduce to FESTIM?

• Bugfix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Code refactoring
• Documentation Update (if none of the other choices apply)
• New tests

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 99.53%. Comparing base (f1f9a71) to head (def3e1d).
Report is 156 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #794   +/-   ##
=======================================
  Coverage   99.53%   99.53%           
=======================================
  Files          59       59           
  Lines        2581     2581           
=======================================
  Hits         2569     2569           
  Misses         12       12           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[danilopeixoto]

@RemDelaporteMathurin Yes. In addition, the following changes will be required:

1. Custom template for distinct sidebar icon links.

Add new template to docs/_templates/sidebar-icon-links.html.

{# Displays icon-links as list items. #}
{%- macro icon_link_nav_item(url, icon, name, type, attributes='') -%}
  {%- if url | length > 2 %}
        <li class="nav-item">
          {%- set attributesDefault = { "href": url, "title": name, "class": "nav-link pst-navbar-icon", "rel": "noopener", "target": "_blank", "data-bs-toggle": "tooltip", "data-bs-placement": "bottom"} %}
          {%- if attributes %}{% for key, val in attributes.items() %}
            {% set _ = attributesDefault.update(attributes) %}
          {% endfor %}{% endif -%}
          {% set attributeString = [] %}
          {% for key, val in attributesDefault.items() %}
            {%- set _ = attributeString.append('%s="%s"' % (key, val)) %}
          {% endfor %}
          {% set attributeString = attributeString | join(" ") -%}
          <a {{ attributeString }}>
            {%- if type == "fontawesome" -%}
            <i class="{{ icon }} fa-lg" aria-hidden="true"></i>
            <span class="sr-only">{{ name }}</span>
            {%- elif type == "local" -%}
            <img src="{{ pathto(icon, 1) }}" class="icon-link-image" alt="{{ name }}"/>
            {%- elif type == "url" -%}
            <img src="{{ icon }}" class="icon-link-image" alt="{{ name }}"/>
            {%- else %}
            <span>Incorrectly configured icon link. Type must be `fontawesome`, `url` or `local`.</span>
            {%- endif -%}
          </a>
        </li>
  {%- endif -%}
{%- endmacro -%}
{%- if sidebar_icon_links -%}
<ul class="navbar-icon-links"
    aria-label="{{ theme_icon_links_label }}">
  {%- for icon_link in sidebar_icon_links -%}
    {{ icon_link_nav_item(icon_link["url"], icon_link["icon"], icon_link["name"], icon_link.get("type", "fontawesome"), icon_link.get("attributes", {})) -}}
  {%- endfor %}
</ul>
{%- endif -%}

2. Custom theme options for templates.

Configure new template and variables.

templates_path = ['_templates'] # provide path for custom templates
html_theme = "sphinx_book_theme"
html_theme_options = {
    'icon_links': [
        {
            'name': 'PyPI',
            'url': 'https://pypi.org/project/jupyterhub-ai-gateway',
            'icon': 'fab fa-python',
        },
    ],
    "article_header_end": [
        "navbar-icon-links",
        "article-header-buttons",
    ],
}
html_context = { # extended template variables
    "sidebar_icon_links": [
        {
            "name": "GitLab",
            "url": "https://gitlab.com/danilopeixoto/jupyterhub-ai-gateway",
            "icon": "fab fa-gitlab",
        },
    ],
}
html_sidebars = {
    "**": [
        "navbar-logo",
        "sidebar-icon-links", # add new template to sidebar
        "search-button-field",
        "sbt-sidebar-nav",
    ],
}

Result:

[RemDelaporteMathurin]

@danilopeixoto thanks! It's a shame there's not a more streamlined option for this 😄