diff --git a/docs/_static/pydata-logo-square.png b/docs/_static/pydata-logo-square.png new file mode 100644 index 0000000000..8c23c23da8 Binary files /dev/null and b/docs/_static/pydata-logo-square.png differ diff --git a/docs/conf.py b/docs/conf.py index cdbcf7aaa4..3e42275815 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -88,7 +88,13 @@ "name": "PyPI", "url": "https://pypi.org/project/pydata-sphinx-theme", "icon": "fas fa-box", - } + }, + { + "name": "PyData", + "url": "https://pydata.org", + "icon": "_static/pydata-logo-square.png", + "type": "local", + }, ], "use_edit_page_button": True, "show_toc_level": 1, diff --git a/docs/user_guide/configuring.rst b/docs/user_guide/configuring.rst index 00d5446154..9c50ea18f2 100644 --- a/docs/user_guide/configuring.rst +++ b/docs/user_guide/configuring.rst @@ -34,8 +34,45 @@ If you'd like it to link to another page or use an external link instead, use th Configure icon links ==================== -If you'd like icon links to show up to the right of your main navigation bar, use the -following configuration: +You can add icon links to show up to the right of your main navigation bar. + +These links take the following form: + +.. code:: python + + html_theme_options = { + ... + "icon_links": [ + { + # Label for this link + "name": "GitHub", + # URL where the link will redirect + "url": "https://github.com//", # required + # Icon class (if type=='fontawesome'), or path to local image (if type=='local') + "icon": "fab fa-github-square", + # Whether icon should be a FontAwesome class, or a local file + "type": "fontawesome OR local", # Default is fontawesome + } + ] + } + +There are two kinds of icons you can use, described below: + +FontAwesome icons +----------------- + +`FontAwesome `_ is a collection of icons that are +commonly used in websites. They include both generic shape icons (e.g., "arrow-down"), +as well as brand-specific icons (e.g. "github"). + +You can use FontAwesome icons by specifying ``type=="fontawesome"``, and +specifying a FontAwesome class in the ``icon`` value. +The value of ``icon`` can be any full +`FontAwesome 5 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*. + +Here are several examples: .. code:: python @@ -46,28 +83,24 @@ following configuration: "name": "GitHub", "url": "https://github.com//", "icon": "fab fa-github-square", + "type": "fontawesome", }, { "name": "GitLab", "url": "https://gitlab.com//", "icon": "fab fa-gitlab", + "type": "fontawesome", }, { "name": "Twitter", "url": "https://twitter.com/", "icon": "fab fa-twitter-square", + # The default for `type` is `fontawesome` so it is not required here }, ], ... } - -The value of ``icon`` can be any full -`FontAwesome 5 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, @@ -81,8 +114,35 @@ also be provided e.g. `fab` for *branding*, or `fas` for *solid*. 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``: +Local image icons +----------------- + +If you'd like to display an icon image that is not in the FontAwesome icons library, +you may instead specify a path to a local image that will be used for the icon. +To do so, use ``type=="local"``, and add a path to an image +**relative to your documentation root** in the ``icon`` value. +Here is an example: + +.. code:: python + + html_theme_options = { + ... + "icon_links": [ + { + "name": "PyData", + "url": "https://pydata.org", + "icon": "_static/pydata-logo-square.png", + "type": "local", + }, + ], + ... + } + +Icon Link Shortcuts +------------------- + +There are a few shortcuts supported to minimize configuration for commonly-used services. +These may be removed in a future release in favor of ``icon_links``: .. code:: python diff --git a/src/pydata_sphinx_theme/assets/styles/index.scss b/src/pydata_sphinx_theme/assets/styles/index.scss index a0dcf5466a..450852e8bf 100644 --- a/src/pydata_sphinx_theme/assets/styles/index.scss +++ b/src/pydata_sphinx_theme/assets/styles/index.scss @@ -457,6 +457,10 @@ nav.bd-links { color: #0052cc; } } + + img.icon-link-image { + height: 1.5em; + } } /* TOC section headers */ diff --git a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/icon-links.html b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/icon-links.html index 4dd3aa9211..0b0b211feb 100644 --- a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/icon-links.html +++ b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/icon-links.html @@ -1,8 +1,14 @@ -{%- macro icon_link_nav_item(url, icon, name) -%} +{%- macro icon_link_nav_item(url, icon, name, type) -%} {%- if url | length > 2 %}
  • + {%- if type == "fontawesome" -%} + {%- elif type == "local" -%} + + {%- else %} + Incorrectly configured icon link. Type must by `fontawesome` or `local`. + {%- endif -%}
    • @@ -11,12 +17,12 @@ diff --git a/tests/test_build.py b/tests/test_build.py index 4e6e0ef2d0..831d000444 100644 --- a/tests/test_build.py +++ b/tests/test_build.py @@ -91,6 +91,46 @@ def test_toc_visibility(sphinx_build_factory): assert "visible" not in index_html.select(".toc-h3 ul")[0].attrs["class"] +def test_icon_links(sphinx_build_factory, file_regression): + html_theme_options_icon_links = { + "icon_links": [ + { + "name": "FONTAWESOME", + "url": "https://site1.org", + "icon": "FACLASS", + "type": "fontawesome", + }, + { + "name": "FONTAWESOME DEFAULT", + "url": "https://site2.org", + "icon": "FADEFAULTCLASS", + # No type so we can test that the default is fontawesome + }, + { + "name": "LOCAL FILE", + "url": "https://site3.org", + "icon": "emptylogo.png", # Logo is our only test site img + "type": "local", + }, + { + "name": "WRONG TYPE", + "url": "https://site4.org", + "icon": "WRONG TYPE", + # Because the type is inccorect, this should output an error `span` + "type": "incorrecttype", + }, + ] + } + confoverrides = {"html_theme_options": html_theme_options_icon_links} + + sphinx_build = sphinx_build_factory("base", confoverrides=confoverrides).build() + # Navbar should have the right icons + icon_links = sphinx_build.html_tree("index.html").select("#navbar-icon-links")[0] + file_regression.check( + icon_links.prettify(), basename="navbar_icon_links", extension=".html" + ) + + def test_logo(sphinx_build_factory): """Test that the logo is shown by default, project title if no logo.""" sphinx_build = sphinx_build_factory("base").build() diff --git a/tests/test_build/icon_links.html b/tests/test_build/icon_links.html deleted file mode 100644 index c315052760..0000000000 --- a/tests/test_build/icon_links.html +++ /dev/null @@ -1,24 +0,0 @@ - diff --git a/tests/test_build/navbar_icon_links.html b/tests/test_build/navbar_icon_links.html new file mode 100644 index 0000000000..604896a60c --- /dev/null +++ b/tests/test_build/navbar_icon_links.html @@ -0,0 +1,43 @@ +