From a4a69793efc864706117d6535f2c8682bda5fc5b Mon Sep 17 00:00:00 2001
From: Gabriel Fouasnon <gabriel@fouasnon.com>
Date: Thu, 21 Sep 2023 11:09:05 +0300
Subject: [PATCH 01/12] Default logo alt text only if no extra text

---
 .../theme/pydata_sphinx_theme/components/navbar-logo.html       | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/navbar-logo.html b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/navbar-logo.html
index 7f82a97c9..f6742e4e0 100644
--- a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/navbar-logo.html
+++ b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/navbar-logo.html
@@ -11,7 +11,7 @@
 <a class="navbar-brand logo" href="{{ href }}">
   {# get all the brand information from html_theme_option #}
   {% set is_logo = "light" in theme_logo["image_relative"] %}
-  {% set alt = theme_logo.get("alt_text", "Logo image") %}
+  {% set alt = theme_logo.get("alt_text", "Logo" if not theme_logo.get("text") else "") %}
   {% if is_logo %}
     {# Theme switching is only available when JavaScript is enabled.
      # Thus we should add the extra image using JavaScript, defaulting

From e1b9f7bba481c34d8c932d5b6dcb87fc758693af Mon Sep 17 00:00:00 2001
From: Gabriel Fouasnon <gabriel@fouasnon.com>
Date: Thu, 21 Sep 2023 11:39:55 +0300
Subject: [PATCH 02/12] change default logo

---
 .../theme/pydata_sphinx_theme/components/navbar-logo.html       | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/navbar-logo.html b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/navbar-logo.html
index f6742e4e0..936031b56 100644
--- a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/navbar-logo.html
+++ b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/navbar-logo.html
@@ -11,7 +11,7 @@
 <a class="navbar-brand logo" href="{{ href }}">
   {# get all the brand information from html_theme_option #}
   {% set is_logo = "light" in theme_logo["image_relative"] %}
-  {% set alt = theme_logo.get("alt_text", "Logo" if not theme_logo.get("text") else "") %}
+  {% set alt = theme_logo.get("alt_text", f"{docstitle} - Home" if not theme_logo.get("text") else "") %}
   {% if is_logo %}
     {# Theme switching is only available when JavaScript is enabled.
      # Thus we should add the extra image using JavaScript, defaulting

From 881847a14a6f9667285c7999a9014566e375677c Mon Sep 17 00:00:00 2001
From: Gabriel Fouasnon <gabriel@fouasnon.com>
Date: Thu, 21 Sep 2023 11:47:00 +0300
Subject: [PATCH 03/12] use docstitle as default logo alt text

---
 .../theme/pydata_sphinx_theme/components/navbar-logo.html       | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/navbar-logo.html b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/navbar-logo.html
index 936031b56..8bd76c112 100644
--- a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/navbar-logo.html
+++ b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/navbar-logo.html
@@ -11,7 +11,7 @@
 <a class="navbar-brand logo" href="{{ href }}">
   {# get all the brand information from html_theme_option #}
   {% set is_logo = "light" in theme_logo["image_relative"] %}
-  {% set alt = theme_logo.get("alt_text", f"{docstitle} - Home" if not theme_logo.get("text") else "") %}
+  {% set alt = theme_logo.get("alt_text", docstitle + " - Home" if not theme_logo.get("text") else "") %}
   {% if is_logo %}
     {# Theme switching is only available when JavaScript is enabled.
      # Thus we should add the extra image using JavaScript, defaulting

From 71c57b1d24b395a0113ea32812c31abda8af8d7d Mon Sep 17 00:00:00 2001
From: Gabriel Fouasnon <gabriel@fouasnon.com>
Date: Thu, 21 Sep 2023 11:59:38 +0300
Subject: [PATCH 04/12] update docs to reflect change

---
 docs/user_guide/branding.rst | 36 +++++++++++++++++++-----------------
 1 file changed, 19 insertions(+), 17 deletions(-)

diff --git a/docs/user_guide/branding.rst b/docs/user_guide/branding.rst
index 43402e8b6..aa258f58a 100644
--- a/docs/user_guide/branding.rst
+++ b/docs/user_guide/branding.rst
@@ -77,41 +77,43 @@ To reference an external website, make sure your link starts with ``http``:
        }
    }
 
-Customize logo alternative text
--------------------------------
-
-You may set a custom ``alt text`` for your logo to replace the default ``"logo image"`` generic description.
-Adding a descriptive ``alt text`` can help make your documentation more accessible to readers using screen readers or another assistive tech.
+Add a logo title
+----------------
 
-To do so, customize the ``html_theme_options["logo"]["alt_text"]`` configuration option as in the following example:
+To add a title in the brand section of your documentation, define a value for ``html_theme_options.logo["text"]``.
+This title will appear next to the logo image if set.
 
 .. code-block:: python
-   :caption: conf.py
 
    html_theme_options = {
        "logo": {
-           # Because the logo is also a homepage link, including "home" in the alt text is good practice
-           "alt_text": "My Project Name - Home",
+           "text": "My awesome documentation",
        }
    }
 
-Add a logo title
-----------------
+.. note:: The ``html_title`` field will work as well if no logo images are specified.
 
-To add a title in the brand section of your documentation, define a value for ``html_theme_options.logo["text"]``.
-This title will appear next to the logo image if set.
+Customize logo alternative text
+-------------------------------
+
+Adding a descriptive ``alt text`` can help make your documentation more accessible to readers using screen readers or other assistive tech.
+
+By default, the theme will set ``alt text`` to ``<Your Project Name> - Home`` unless you provide a logo title, in which case the theme sets the ``alt text`` to the empty string. The assumption is that if you provide a logo title, the title is probably doing the work of the alt text.
+
+However, if you don't like the default values, you may set a custom ``alt text`` for your logo.
+
+To do so, customize the ``html_theme_options["logo"]["alt_text"]`` configuration option as in the following example:
 
 .. code-block:: python
+   :caption: conf.py
 
    html_theme_options = {
        "logo": {
-           "text": "My awesome documentation",
+           # Because the logo is also a homepage link, including "home" in the alt text is good practice
+           "alt_text": "My Project Name - Home",
        }
    }
 
-.. note:: The ``html_title`` field will work as well if no logo images are specified.
-
-
 Add favicons
 ============
 

From 36f1fe5edf93ca27cc1119e406c29cc0d5502039 Mon Sep 17 00:00:00 2001
From: gabalafou <gabriel@fouasnon.com>
Date: Thu, 21 Sep 2023 10:37:26 -0500
Subject: [PATCH 05/12] Apply suggestions from code review

Co-authored-by: Daniel McCloy <dan@mccloy.info>
---
 docs/user_guide/branding.rst                                  | 4 ++--
 .../theme/pydata_sphinx_theme/components/navbar-logo.html     | 3 ++-
 2 files changed, 4 insertions(+), 3 deletions(-)

diff --git a/docs/user_guide/branding.rst b/docs/user_guide/branding.rst
index aa258f58a..699e764ca 100644
--- a/docs/user_guide/branding.rst
+++ b/docs/user_guide/branding.rst
@@ -91,12 +91,12 @@ This title will appear next to the logo image if set.
        }
    }
 
-.. note:: The ``html_title`` field will work as well if no logo images are specified.
+.. note:: Sphinx's standard ``html_title`` variable in ``conf.py`` will work as well if no logo images are specified.
 
 Customize logo alternative text
 -------------------------------
 
-Adding a descriptive ``alt text`` can help make your documentation more accessible to readers using screen readers or other assistive tech.
+Adding a descriptive ``alt text`` can help make your documentation more accessible to people using screen readers or other assistive tech.
 
 By default, the theme will set ``alt text`` to ``<Your Project Name> - Home`` unless you provide a logo title, in which case the theme sets the ``alt text`` to the empty string. The assumption is that if you provide a logo title, the title is probably doing the work of the alt text.
 
diff --git a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/navbar-logo.html b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/navbar-logo.html
index 8bd76c112..a556a4e97 100644
--- a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/navbar-logo.html
+++ b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/navbar-logo.html
@@ -11,7 +11,8 @@
 <a class="navbar-brand logo" href="{{ href }}">
   {# get all the brand information from html_theme_option #}
   {% set is_logo = "light" in theme_logo["image_relative"] %}
-  {% set alt = theme_logo.get("alt_text", docstitle + " - Home" if not theme_logo.get("text") else "") %}
+  {# use alt_text if given. If not, only add alttext if no add'l branding text given. #}
+  {% set alt = theme_logo.get("alt_text", "" if theme_logo.get("text") else f"{docstitle} - Home") %}
   {% if is_logo %}
     {# Theme switching is only available when JavaScript is enabled.
      # Thus we should add the extra image using JavaScript, defaulting

From c54c0acf552df490b106e3ccaf25efeb516c1f6c Mon Sep 17 00:00:00 2001
From: Gabriel Fouasnon <gabriel@fouasnon.com>
Date: Thu, 21 Sep 2023 18:42:51 +0300
Subject: [PATCH 06/12] use string formatting operator

---
 .../theme/pydata_sphinx_theme/components/navbar-logo.html       | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/navbar-logo.html b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/navbar-logo.html
index a556a4e97..681cbcc67 100644
--- a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/navbar-logo.html
+++ b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/navbar-logo.html
@@ -12,7 +12,7 @@
   {# get all the brand information from html_theme_option #}
   {% set is_logo = "light" in theme_logo["image_relative"] %}
   {# use alt_text if given. If not, only add alttext if no add'l branding text given. #}
-  {% set alt = theme_logo.get("alt_text", "" if theme_logo.get("text") else f"{docstitle} - Home") %}
+  {% set alt = theme_logo.get("alt_text", "" if theme_logo.get("text") else "%s - Home" % docstitle) %}
   {% if is_logo %}
     {# Theme switching is only available when JavaScript is enabled.
      # Thus we should add the extra image using JavaScript, defaulting

From 3430634dfb15dc9387dd47bb1816780bbf8d2736 Mon Sep 17 00:00:00 2001
From: gabalafou <gabriel@fouasnon.com>
Date: Tue, 26 Sep 2023 03:21:17 -0500
Subject: [PATCH 07/12] Update docs/user_guide/branding.rst

---
 docs/user_guide/branding.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/user_guide/branding.rst b/docs/user_guide/branding.rst
index 699e764ca..f66dd0af5 100644
--- a/docs/user_guide/branding.rst
+++ b/docs/user_guide/branding.rst
@@ -98,7 +98,7 @@ Customize logo alternative text
 
 Adding a descriptive ``alt text`` can help make your documentation more accessible to people using screen readers or other assistive tech.
 
-By default, the theme will set ``alt text`` to ``<Your Project Name> - Home`` unless you provide a logo title, in which case the theme sets the ``alt text`` to the empty string. The assumption is that if you provide a logo title, the title is probably doing the work of the alt text.
+By default, the theme will set ``alt text`` to "`docstitle <https://www.sphinx-doc.org/en/master/development/templating.html#docstitle>`_ - Home" unless you provide a logo title, in which case the theme sets the ``alt text`` to the empty string. The assumption is that if you provide a logo title, the title is probably doing the work of the alt text.
 
 However, if you don't like the default values, you may set a custom ``alt text`` for your logo.
 

From 442e776daf1ea19e0c747fd711a047d69f57a028 Mon Sep 17 00:00:00 2001
From: Gabriel Fouasnon <gabriel@fouasnon.com>
Date: Tue, 26 Sep 2023 12:50:08 +0300
Subject: [PATCH 08/12] docs fixes

---
 docs/user_guide/branding.rst                  | 55 ++++++++++++++-----
 .../components/navbar-logo.html               |  2 +-
 2 files changed, 41 insertions(+), 16 deletions(-)

diff --git a/docs/user_guide/branding.rst b/docs/user_guide/branding.rst
index f66dd0af5..671fa04b7 100644
--- a/docs/user_guide/branding.rst
+++ b/docs/user_guide/branding.rst
@@ -77,43 +77,68 @@ To reference an external website, make sure your link starts with ``http``:
        }
    }
 
-Add a logo title
-----------------
+Logo title and alternative text
+-------------------------------
 
-To add a title in the brand section of your documentation, define a value for ``html_theme_options.logo["text"]``.
-This title will appear next to the logo image if set.
+If you provide a logo image, it replaces ``project`` or ``html_title`` in the
+header nav bar. If you want to display both your site's logo and title (or any
+other text) next to the logo, you provide it with the ``text`` property like so:
 
 .. code-block:: python
+   :caption: conf.py
 
    html_theme_options = {
        "logo": {
            "text": "My awesome documentation",
+           "image_light": "_static/logo-light.png",
+           "image_dark": "_static/logo-dark.png",
        }
    }
 
-.. note:: Sphinx's standard ``html_title`` variable in ``conf.py`` will work as well if no logo images are specified.
-
-Customize logo alternative text
--------------------------------
-
-Adding a descriptive ``alt text`` can help make your documentation more accessible to people using screen readers or other assistive tech.
+But if you only want to display the logo and not the site title, then it's good
+practice to provide alt text, which helps blind visitors and others who rely on
+screen readers:
 
-By default, the theme will set ``alt text`` to "`docstitle <https://www.sphinx-doc.org/en/master/development/templating.html#docstitle>`_ - Home" unless you provide a logo title, in which case the theme sets the ``alt text`` to the empty string. The assumption is that if you provide a logo title, the title is probably doing the work of the alt text.
+.. code-block:: python
+   :caption: conf.py
 
-However, if you don't like the default values, you may set a custom ``alt text`` for your logo.
+   html_theme_options = {
+       "logo": {
+           # Because the logo is also a homepage link, including "home" in the
+           # alt text is good practice
+           "alt_text": "My awesome documentation - Home",
+           "image_light": "_static/logo-light.png",
+           "image_dark": "_static/logo-dark.png",
+       }
+   }
 
-To do so, customize the ``html_theme_options["logo"]["alt_text"]`` configuration option as in the following example:
+In most cases, you will provide either ``text`` or ``alt_text``, not both, but
+there are some circumstances in which it may make sense to provide both:
 
 .. code-block:: python
    :caption: conf.py
 
    html_theme_options = {
        "logo": {
-           # Because the logo is also a homepage link, including "home" in the alt text is good practice
-           "alt_text": "My Project Name - Home",
+           # In a left-to-right context, screen readers will read the alt text
+           # first, then the text, so this example will be read as "P-G-G-P-Y
+           # (short pause) Home A pretty good geometry package"
+           "alt_text": "PggPy - Home",
+           "text": "A pretty good geometry package",
+           "image_light": "_static/logo-light.png",
+           "image_dark": "_static/logo-dark.png",
        }
    }
 
+If you do not provide ``text`` or ``alt_text``, the theme will provide some
+default alt text. (Otherwise, your homepage link would appear to assistive tech
+as something like "Unlabeled image.") By default, the theme will set logo image
+alt text to "`docstitle
+<https://www.sphinx-doc.org/en/master/development/templating.html#docstitle>`_ -
+Home" unless you provide a logo title (``text``), in which case the theme sets
+the alt text to the empty string. (The assumption is that if you provide a logo
+title, the title is probably doing the work of the alt text.)
+
 Add favicons
 ============
 
diff --git a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/navbar-logo.html b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/navbar-logo.html
index 681cbcc67..70eda6c53 100644
--- a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/navbar-logo.html
+++ b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/navbar-logo.html
@@ -11,7 +11,7 @@
 <a class="navbar-brand logo" href="{{ href }}">
   {# get all the brand information from html_theme_option #}
   {% set is_logo = "light" in theme_logo["image_relative"] %}
-  {# use alt_text if given. If not, only add alttext if no add'l branding text given. #}
+  {# use alt_text if given. If not, only add alt text if no additional branding text given. #}
   {% set alt = theme_logo.get("alt_text", "" if theme_logo.get("text") else "%s - Home" % docstitle) %}
   {% if is_logo %}
     {# Theme switching is only available when JavaScript is enabled.

From 3850784f0890799bf5eb67b6418fd3a2f944dff1 Mon Sep 17 00:00:00 2001
From: Daniel McCloy <dan@mccloy.info>
Date: Tue, 26 Sep 2023 09:54:05 -0500
Subject: [PATCH 09/12] Update docs/user_guide/branding.rst

---
 docs/user_guide/branding.rst | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/docs/user_guide/branding.rst b/docs/user_guide/branding.rst
index 671fa04b7..40ba7b2d2 100644
--- a/docs/user_guide/branding.rst
+++ b/docs/user_guide/branding.rst
@@ -131,13 +131,13 @@ there are some circumstances in which it may make sense to provide both:
    }
 
 If you do not provide ``text`` or ``alt_text``, the theme will provide some
-default alt text. (Otherwise, your homepage link would appear to assistive tech
-as something like "Unlabeled image.") By default, the theme will set logo image
-alt text to "`docstitle
+default alt text (otherwise, your homepage link would appear to assistive tech
+as something like "Unlabeled image"). The default alt text is "`docstitle
 <https://www.sphinx-doc.org/en/master/development/templating.html#docstitle>`_ -
-Home" unless you provide a logo title (``text``), in which case the theme sets
-the alt text to the empty string. (The assumption is that if you provide a logo
-title, the title is probably doing the work of the alt text.)
+Home", but if you provide a logo title (``text``) the default alt text will be an
+empty string (the assumption is that if you provide a logo title, the title is
+probably doing the work of the alt text, and as shown above, you can override
+this assumption by supplying both ``text`` and ``alt_text``).
 
 Add favicons
 ============

From 7cbcc32c3ce1118ff74cbdc89d8f2aafeb294be3 Mon Sep 17 00:00:00 2001
From: Daniel McCloy <dan@mccloy.info>
Date: Tue, 26 Sep 2023 10:46:43 -0500
Subject: [PATCH 10/12] add test

---
 tests/test_build.py | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/tests/test_build.py b/tests/test_build.py
index 6cfc37d07..5889f549c 100644
--- a/tests/test_build.py
+++ b/tests/test_build.py
@@ -115,6 +115,22 @@ def test_icon_links(sphinx_build_factory, file_regression) -> None:
     )
 
 
+@pytest.mark.parametrize(
+    "confoverrides,expected_alt_text",
+    (
+        [dict(), "PyData Tests  documentation - Home"],
+        [dict(html_theme_options=dict(logo=dict(text="Foo"))), ""],
+        [dict(html_theme_options=dict(logo=dict(text="Foo", alt_text="Bar"))), "Bar"],
+    ),
+)
+def test_logo_alt_text(sphinx_build_factory, confoverrides, expected_alt_text) -> None:
+    """Test our alt-text fallback mechanism."""
+    sphinx_build = sphinx_build_factory("base", confoverrides=confoverrides).build()
+    index_html = sphinx_build.html_tree("index.html")
+    logo_image = index_html.select(".navbar-brand img")[0]
+    assert logo_image.attrs["alt"] == expected_alt_text
+
+
 def test_logo_basic(sphinx_build_factory) -> None:
     """Test that the logo is shown by default, project title if no logo."""
     sphinx_build = sphinx_build_factory("base").build()

From b75cf0f9ffe95f0340f9fd3b784f71691ee0e535 Mon Sep 17 00:00:00 2001
From: Rambaud Pierrick <12rambau@users.noreply.github.com>
Date: Wed, 27 Sep 2023 07:09:20 +0000
Subject: [PATCH 11/12] Update pyproject.toml

---
 pyproject.toml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/pyproject.toml b/pyproject.toml
index 05f162a50..7e85bfcef 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -54,7 +54,7 @@ doc = [
   "rich",
   "sphinxext-rediraffe",
   "sphinx-sitemap",
-  "sphinx-autoapi",
+  "sphinx-autoapi>=3",
   # For examples section
   "ablog>=0.11.0rc2",
   "jupyter_sphinx",

From a83bca28bbd90112cd4fac37791dc9076ca658af Mon Sep 17 00:00:00 2001
From: Rambaud Pierrick <12rambau@users.noreply.github.com>
Date: Wed, 27 Sep 2023 07:39:41 +0000
Subject: [PATCH 12/12] revert to original

---
 pyproject.toml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/pyproject.toml b/pyproject.toml
index 7e85bfcef..05f162a50 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -54,7 +54,7 @@ doc = [
   "rich",
   "sphinxext-rediraffe",
   "sphinx-sitemap",
-  "sphinx-autoapi>=3",
+  "sphinx-autoapi",
   # For examples section
   "ablog>=0.11.0rc2",
   "jupyter_sphinx",