ENH: Adding logo image for dark mode (#231)

* dark logo code

* testing if CI works okay

* removing windows test

* configuration for dark_logo

.github/workflows/tests.yml

@@ -11,39 +11,50 @@ jobs:
   pre-commit:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - uses: actions/setup-python@v4
       with:
-        python-version: "3.10"
+        python-version: 3.11
     - uses: pre-commit/[email protected]
 
   tests:
-    runs-on: ubuntu-latest
     strategy:
+      fail-fast: false
       matrix:
-        python-version: [3.9, "3.10"]
+        os: [ubuntu-latest]
+        python-version: ["3.9", "3.10", "3.11"]
+        # Only test the latest major release of Sphinx because otherwise we need to
+        # keep multiple versions of regression tests on file and this creates lots of
+        # noise in the tests.
+        sphinx: ["~=5.0"]
+        include:
+        - os: macos-latest
+          python-version: 3.x
+    runs-on: ${{ matrix.os }}
+
     steps:
-    - uses: actions/checkout@v3
-    - name: Set up Python ${{ matrix.python-version }} and Sphinx ${{ matrix.sphinx }}
+    - uses: actions/checkout@v4
+    - name: Set up Python ${{ matrix.python-version }}
       uses: actions/setup-python@v4
       with:
         python-version: ${{ matrix.python-version }}
         cache: "pip"
         cache-dependency-path: "pyproject.toml"
 
-    - name: Install dependencies
+    - name: Install dependencies with Sphinx ${{ matrix.sphinx }}
       run: |
         python -m pip install --upgrade pip
-        python -m pip install -e .[test]
+        python -m pip install --upgrade "sphinx${{matrix.sphinx}}" -e .[test] --pre
+
     - name: Run pytest
       run: >
         pytest --durations=10 --cov=quantecon_book_theme --cov-report=xml --cov-report=term-missing
 
     - name: Upload to Codecov
-      if: github.repository == 'QuantEcon/quantecon-book-theme'
-      uses: codecov/[email protected].0
+      if: matrix.os == 'ubuntu-latest' && matrix.python-version == 3.9 && github.repository == 'QuantEcon/quantecon-book-theme' && github.event_name == 'pull_request'
+      uses: codecov/[email protected].4
       with:
-        name: ebp-qbt-pytests-${{ matrix.python-version}}
+        name: ebp-qbt-pytests-py3.7
         flags: pytests
         file: ./coverage.xml
         fail_ci_if_error: true

docs/configure.md

@@ -114,3 +114,18 @@ html_theme_options = {
     ...
 }
 ```
+
+## Add a dark mode version of your logo
+
+To optimize your branding for dark mode, consider creating a dedicated dark mode variant of your logo.
+Then, configure the theme settings to display this variant when dark mode is active, using the following configuration:
+
+```python
+html_theme_options = {
+    ...
+    "dark_logo": "name-of-dark-logo-image"
+    ...
+}
+```
+
+The image is expected to be in the `_static` folder of your source repository.

src/quantecon_book_theme/assets/scripts/index.js

@@ -56,6 +56,8 @@ document.addEventListener("DOMContentLoaded", function () {
     $head = $("head"),
     $body = $("body"),
     $sidebar = $(".qe-sidebar"),
+    $lighLogo = $(".logo-img"),
+    $darkLogo = $(".dark-logo-img"),
     $sidebarToggle = $(".btn__sidebar");
 
   // Toolbar contrast toggle
@@ -83,6 +85,9 @@ document.addEventListener("DOMContentLoaded", function () {
       $(this).addClass("btn-active");
       localStorage.setContrast = 1;
       $body.addClass("dark-theme");
+      if (!$darkLogo.length) {
+        $lighLogo.css("display", "block");
+      }
     }
   });
 

src/quantecon_book_theme/assets/styles/index.scss

@@ -99,6 +99,14 @@ body {
     max-width: 100%;
   }
 
+  .logo-img {
+    display: block;
+  }
+
+  .dark-logo-img {
+    display: none;
+  }
+
   &.dark-theme {
     background: #222;
     color: #fff;
@@ -129,6 +137,14 @@ body {
       color: #fff !important;
     }
 
+    .logo-img {
+      display: none;
+    }
+
+    .dark-logo-img {
+      display: block;
+    }
+
     .highlight {
       background: #111 !important;
       .n,

src/quantecon_book_theme/theme/quantecon_book_theme/layout.html

@@ -106,7 +106,10 @@
                             <p class="logo">
                                 {% if logo %}
                                     {% if theme_header_organisation_url %}
-                                    <a href={{theme_header_organisation_url}}><img src="{{ pathto('_static/' + logo, 1) }}" class="logo" alt="logo"></a>
+                                    <a href={{theme_header_organisation_url}}><img src="{{ pathto('_static/' + logo, 1) }}" class="logo logo-img" alt="logo"></a>
+                                    {% if theme_dark_logo %}
+                                    <a href={{theme_header_organisation_url}}><img src="{{ pathto('_static/' + theme_dark_logo, 1) }}" class="dark-logo-img" alt="logo"></a>
+                                    {% endif %}
                                     {% else %}
                                     <a href="{{ master_url }}"><img src="{{ pathto('_static/' + logo, 1) }}" class="logo" alt="logo"></a>
                                     {% endif %}

src/quantecon_book_theme/theme/quantecon_book_theme/theme.conf

@@ -28,3 +28,4 @@ twitter =
 twitter_logo_url =
 og_logo_url =
 persistent_sidebar = False
+dark_logo =

tests/sites/base/conf.py

@@ -23,6 +23,7 @@
     "path_to_docs": "TESTPATH",
     "repository_url": "https://github.com/executablebooks/sphinx-book-theme",
     "nb_repository_url": "https://github.com/executablebooks/sphinx-book-theme",
+    "navigation_with_keys": True,
     # "repository_branch": "master",  # Not using this, should default to master
     "launch_buttons": {
         "binderhub_url": "https://mybinder.org",