diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 1428b1054..5a4d9db02 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -28,27 +28,16 @@ jobs: fail-fast: false matrix: os: [ubuntu-latest] - python-version: ["3.10", "3.11", "3.12.*", "3.13"] - # 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: ["~=6.0","~=7.0", "~=8.0"] + python-version: ["3.11", "3.12", "3.13"] + # Test last 2 major releases of Sphinx; regression fixtures target the latest. + sphinx: ["~=7.0", "~=8.0"] include: - os: windows-latest - # Python 3.12 is broken on windows builds until the following PR is released: - # https://github.com/pradyunsg/sphinx-theme-builder/pull/47 - python-version: 3.11 + python-version: 3.13 # Windows pulling in dependencies fails experimental: true - os: macos-latest python-version: 3.x - # Sphinx <8 is 3.9+ - - os: ubuntu-latest - python-version: "3.9" - sphinx: "~=7.0" - - os: ubuntu-latest - python-version: "3.9" - sphinx: "~=6.0" runs-on: ${{ matrix.os }} @@ -73,10 +62,10 @@ jobs: # Only upload to codecov on pull requests so that we don't trigger rate limit blocks # Disabled for now with false && - name: Upload to Codecov - if: false && matrix.os == 'ubuntu-latest' && matrix.python-version == 3.9 && matrix.sphinx == '~=7.0' && github.repository == 'executablebooks/sphinx-book-theme' && github.event_name == 'pull_request' + if: false && matrix.os == 'ubuntu-latest' && matrix.python-version == '3.11' && matrix.sphinx == '~=8.0' && github.repository == 'executablebooks/sphinx-book-theme' && github.event_name == 'pull_request' uses: codecov/codecov-action@v5.0.7 with: - name: ebp-sbt-pytests-py3.7 + name: ebp-sbt-pytests-py3.11 flags: pytests file: ./coverage.xml fail_ci_if_error: true @@ -90,7 +79,7 @@ jobs: - name: Set up Python uses: actions/setup-python@v5 with: - python-version: '3.9' + python-version: '3.13' cache: "pip" cache-dependency-path: "pyproject.toml" - name: Install fonts diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 257b3ae83..db3875dd4 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -2,7 +2,7 @@ This is a short overview of the general architecture and structure of the repository, to help you orient yourself. -This theme uses [sphinx-theme-builder](https://sphinx-theme-builder.readthedocs.io/en/latest/) as its build backend, and follows the [filesystem layout](https://sphinx-theme-builder.readthedocs.io/en/latest/filesystem-layout/) recommended by it. +This theme uses [sphinx-theme-builder](https://sphinx-theme-builder.readthedocs.io/en/latest/) as its build backend, and follows the [filesystem layout](https://sphinx-theme-builder.readthedocs.io/en/latest/filesystem-layout.html) recommended by it. See below for some more specific sections ```{contents} diff --git a/README.md b/README.md index cc24ca2be..5723650f6 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,9 @@ [![codecov][codecov-badge]][codecov-link] [![Documentation Status][rtd-badge]][rtd-link] [![PyPI][pypi-badge]][pypi-link] +> [!NOTE] +> **Maintenance Mode**: This project is currently in maintenance mode. We are accepting bug fixes as best we can, but there are not dedicated resources to review and merge. New feature development is not likely. If you're interested in becoming a maintainer and helping keep this project actively developed, please reach out by opening an issue! + **An interactive book theme for Sphinx**. This is a lightweight Sphinx theme designed to mimic the look-and-feel of an diff --git a/docs/contributing/tests.md b/docs/contributing/tests.md index d315aa212..d3389324e 100644 --- a/docs/contributing/tests.md +++ b/docs/contributing/tests.md @@ -14,8 +14,8 @@ $ tox You can specify a specific environment like so: ```console -# Run the tests with Python 3.9, Sphinx 4 -$ tox -e py39-sphinx4 +# Run the tests with Python 3.10, Sphinx 6 +$ tox -e py310-sphinx6 ``` ## List all test environments @@ -46,7 +46,7 @@ By default, `tox` will only install the necessary environment **once**. If you'd like to force a re-build, use the `-r` parameter. For example: ```console -$ tox -r -e py38-sphinx3 +$ tox -r -e py310-sphinx6 ``` ## Test audits with lighthouse @@ -63,8 +63,8 @@ To preview the output of these tests: ## Test multiple Sphinx versions -This theme is tested against the latest two major versions of Sphinx. -We try to set up our regression tests such that there are no differences between these two Sphinx versions. +This theme is tested against Sphinx 6-9. +We try to set up our regression tests such that there are no differences between these Sphinx versions. ### Unit tests @@ -73,9 +73,9 @@ Use the variable `sphinx_build.software_versions` to conditionally run tests bas For example: ```python -if sphinx_build.software_versions == ".sphinx3": +if sphinx_build.software_versions == ".sphinx8": foo -elif sphinx_build.software_versions == ".sphinx4": +elif sphinx_build.software_versions == ".sphinx9": bar ``` diff --git a/docs/reference/extensions.md b/docs/reference/extensions.md index bc72297f8..918543165 100644 --- a/docs/reference/extensions.md +++ b/docs/reference/extensions.md @@ -108,4 +108,25 @@ This toggle is in the margin! ## `sphinx-design` for UI components +[`sphinx-design`](https://sphinx-design.readthedocs.io/) provides various UI components like badges, cards, and dropdowns. + +**Badge:** + {bdg-primary}`Test badge`. + +**Card:** + +::::{card} Card Title +:class-card: sd-border-0 +Card header. +^^^ +Card content goes here. This demonstrates how cards look in both light and dark modes. ++++ +Card footer. +:::: + +**Dropdown:** + +:::{dropdown} Click to expand +This is the dropdown content. It should be readable in both light and dark modes. +::: diff --git a/pyproject.toml b/pyproject.toml index 290291cff..2c255d740 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -37,7 +37,7 @@ readme = "README.md" requires-python = ">=3.9" dependencies = [ "sphinx>=6.1", - "pydata-sphinx-theme==0.15.4" + "pydata-sphinx-theme==0.16.1" ] license = { file = "LICENSE" } diff --git a/src/sphinx_book_theme/assets/scripts/index.js b/src/sphinx_book_theme/assets/scripts/index.js index 372e2639b..256f2a71e 100644 --- a/src/sphinx_book_theme/assets/scripts/index.js +++ b/src/sphinx_book_theme/assets/scripts/index.js @@ -181,8 +181,70 @@ function addNoPrint() { window.initThebeSBT = initThebeSBT; window.toggleFullScreen = toggleFullScreen; +/** + * Add blur behavior to buttons with tooltips + * This prevents tooltips from persisting after clicking buttons + */ +function addBlurToButtons() { + // List of button selectors that should blur on click to dismiss tooltips + const buttonSelectors = [ + ".theme-switch-button", + ".search-button", + ".primary-toggle", + ".secondary-toggle", + ]; + + // Add blur on click for each button type + buttonSelectors.forEach((selector) => { + const button = document.querySelector(selector); + if (button) { + button.addEventListener( + "click", + () => { + button.blur(); + }, + true, + ); + } + }); +} + +/** + * Fix sidebar toggle behavior for wide screens + * On wide screens (>= 992px), clicking the toggle should collapse the sidebar, + * not open it as a dialog modal. The dialog behavior is only for narrow screens. + */ +function fixSidebarToggle() { + const primaryToggle = document.querySelector(".primary-toggle"); + const primarySidebar = document.querySelector("#pst-primary-sidebar"); + const primaryDialog = document.querySelector("#pst-primary-sidebar-modal"); + + // Fix primary sidebar toggle + if (primaryToggle && primarySidebar && primaryDialog) { + // Intercept clicks on the toggle button BEFORE pydata-sphinx-theme's handler + primaryToggle.addEventListener( + "click", + (event) => { + const isWideScreen = window.matchMedia("(min-width: 992px)").matches; + + if (isWideScreen) { + // On wide screens, prevent the dialog from opening and toggle sidebar visibility instead + event.preventDefault(); + event.stopImmediatePropagation(); + + // Toggle a class to hide/show the sidebar + primarySidebar.classList.toggle("pst-sidebar-hidden"); + } + }, + true, + ); // Use capture phase to run before PST's handler + } +} + /** * Set up functions to load when the DOM is ready */ sbRunWhenDOMLoaded(initTocHide); sbRunWhenDOMLoaded(addNoPrint); +sbRunWhenDOMLoaded(addBlurToButtons); +sbRunWhenDOMLoaded(fixSidebarToggle); diff --git a/src/sphinx_book_theme/assets/styles/content/_admonitions.scss b/src/sphinx_book_theme/assets/styles/content/_admonitions.scss new file mode 100644 index 000000000..b00257f90 --- /dev/null +++ b/src/sphinx_book_theme/assets/styles/content/_admonitions.scss @@ -0,0 +1,29 @@ +/** + * Standard Sphinx admonitions + * Improves contrast and readability in dark mode + * Fixes: https://github.com/executablebooks/sphinx-book-theme/issues/743 + */ + +// Ensure admonition titles have proper contrast in dark mode +html[data-theme="dark"] { + .admonition { + .admonition-title { + // Ensure text is always readable by using a color that contrasts well + // with the admonition background colors + color: var(--pst-color-text-base); + + // Add a slight text shadow for better readability on colored backgrounds + text-shadow: 0 1px 2px rgba(0, 0, 0, 0.3); + } + } +} + +// Light mode improvements for consistency +html[data-theme="light"] { + .admonition { + .admonition-title { + // Ensure consistent text rendering + color: var(--pst-color-text-base); + } + } +} diff --git a/src/sphinx_book_theme/assets/styles/extensions/_myst-nb.scss b/src/sphinx_book_theme/assets/styles/extensions/_myst-nb.scss new file mode 100644 index 000000000..96349c8cb --- /dev/null +++ b/src/sphinx_book_theme/assets/styles/extensions/_myst-nb.scss @@ -0,0 +1,18 @@ +/** + * MyST-NB extension + * Improves contrast and readability in dark mode + * Fixes: https://github.com/executablebooks/sphinx-book-theme/issues/743 + */ + +// Ensure hide-input tags have proper contrast in dark mode +html[data-theme="dark"] { + .tag_hide_input .cell_input { + summary { + color: var(--pst-color-link); + + &:hover { + color: var(--pst-color-link-hover); + } + } + } +} diff --git a/src/sphinx_book_theme/assets/styles/extensions/_sphinx-design.scss b/src/sphinx_book_theme/assets/styles/extensions/_sphinx-design.scss new file mode 100644 index 000000000..f6bcd0c6b --- /dev/null +++ b/src/sphinx_book_theme/assets/styles/extensions/_sphinx-design.scss @@ -0,0 +1,18 @@ +/** + * sphinx-design extension + * Improves contrast and readability in dark mode + * Fixes: https://github.com/executablebooks/sphinx-book-theme/issues/743 + */ + +// Ensure sphinx-design cards and dropdowns have proper contrast in dark mode +html[data-theme="dark"] { + .sd-card, + .sd-dropdown { + .sd-card-header, + .sd-card-title, + .sd-summary-title { + color: var(--pst-color-text-base); + text-shadow: 0 1px 2px rgba(0, 0, 0, 0.3); + } + } +} diff --git a/src/sphinx_book_theme/assets/styles/extensions/_sphinx-tabs.scss b/src/sphinx_book_theme/assets/styles/extensions/_sphinx-tabs.scss new file mode 100644 index 000000000..e461959e6 --- /dev/null +++ b/src/sphinx_book_theme/assets/styles/extensions/_sphinx-tabs.scss @@ -0,0 +1,34 @@ +/** + * sphinx-tabs extension + * Improves contrast and readability in dark mode + * Fixes: https://github.com/executablebooks/sphinx-book-theme/issues/743 + */ + +// Ensure sphinx-tabs have proper contrast in dark mode +html[data-theme="dark"] { + .sphinx-tabs { + // Tab buttons + .sphinx-tabs-tab { + background-color: var(--pst-color-surface); + color: var(--pst-color-text-muted); + border-color: var(--pst-color-border); + + &[aria-selected="true"] { + background-color: var(--pst-color-background); + color: var(--pst-color-text-base); + border-bottom-color: var(--pst-color-background); + } + + &:hover { + color: var(--pst-color-text-base); + } + } + + // Tab panel content area + .sphinx-tabs-panel { + background-color: var(--pst-color-background); + color: var(--pst-color-text-base); + border-color: var(--pst-color-border); + } + } +} diff --git a/src/sphinx_book_theme/assets/styles/extensions/_sphinx-togglebutton.scss b/src/sphinx_book_theme/assets/styles/extensions/_sphinx-togglebutton.scss new file mode 100644 index 000000000..3a47807a9 --- /dev/null +++ b/src/sphinx_book_theme/assets/styles/extensions/_sphinx-togglebutton.scss @@ -0,0 +1,19 @@ +/** + * sphinx-togglebutton extension + * Improves contrast and readability in dark mode + * Fixes: https://github.com/executablebooks/sphinx-book-theme/issues/743 + */ + +// Ensure toggle button expand links have proper contrast in dark mode +html[data-theme="dark"] { + details.above-input, + details.below-input { + summary { + color: var(--pst-color-link); + + &:hover { + color: var(--pst-color-link-hover); + } + } + } +} diff --git a/src/sphinx_book_theme/assets/styles/index.scss b/src/sphinx_book_theme/assets/styles/index.scss index 8c8d1293f..2a05f7ae1 100644 --- a/src/sphinx_book_theme/assets/styles/index.scss +++ b/src/sphinx_book_theme/assets/styles/index.scss @@ -33,6 +33,7 @@ @use "components/search"; // Content blocks in standard Sphinx +@use "content/admonitions"; @use "content/images"; @use "content/margin"; @use "content/quotes"; @@ -42,4 +43,8 @@ // Content blocks from Sphinx extensions @use "extensions/comments"; +@use "extensions/myst-nb"; +@use "extensions/sphinx-design"; +@use "extensions/sphinx-tabs"; +@use "extensions/sphinx-togglebutton"; @use "extensions/thebe"; diff --git a/src/sphinx_book_theme/assets/styles/sections/_sidebar-primary.scss b/src/sphinx_book_theme/assets/styles/sections/_sidebar-primary.scss index f446759f4..ba026a3ce 100644 --- a/src/sphinx_book_theme/assets/styles/sections/_sidebar-primary.scss +++ b/src/sphinx_book_theme/assets/styles/sections/_sidebar-primary.scss @@ -18,6 +18,15 @@ opacity variables.$animation-time ease 0s, visibility variables.$animation-time ease 0s; + // Hide sidebar when toggle button is clicked on wide screens + &.pst-sidebar-hidden { + @media (min-width: variables.$breakpoint-lg) { + margin-left: -(variables.$sidebar-primary-width-widescreen); + visibility: hidden; + opacity: 0; + } + } + @media (max-width: variables.$breakpoint-md) { // So that tooltips don't overlap z-index: variables.$zindex-tooltip + 1; @@ -28,6 +37,13 @@ border-top: none; } + // Left-align icon badges with standard gap spacing instead of centering + .navbar-icon-links { + display: flex !important; + justify-content: flex-start !important; + gap: 0.5rem !important; + } + // On wide screens we have a smaller sidebar width than PST @media (min-width: variables.$breakpoint-lg) { flex-basis: variables.$sidebar-primary-width-widescreen; diff --git a/src/sphinx_book_theme/assets/styles/sections/_sidebar-secondary.scss b/src/sphinx_book_theme/assets/styles/sections/_sidebar-secondary.scss index 103bb1ab6..b8d00be47 100644 --- a/src/sphinx_book_theme/assets/styles/sections/_sidebar-secondary.scss +++ b/src/sphinx_book_theme/assets/styles/sections/_sidebar-secondary.scss @@ -46,8 +46,8 @@ // To make sure it shows above the page content z-index: variables.$zindex-middle; - // Remove padding so that it's flush on the top and left - padding: 0; + // Add comfortable horizontal padding, keep flush with top + padding: 0 1.5rem; // This is the container div for the secondary sidebar nav .toc-item { @@ -82,7 +82,7 @@ .onthispage:after { opacity: 1; content: "\f107"; - font-family: "Font Awesome 5 Free"; + font-family: "Font Awesome 6 Free"; font-weight: 900; padding-left: 0.5em; transition: opacity 0.3s ease; diff --git a/src/sphinx_book_theme/header_buttons/__init__.py b/src/sphinx_book_theme/header_buttons/__init__.py index 3da1736a8..8bd14a0c6 100644 --- a/src/sphinx_book_theme/header_buttons/__init__.py +++ b/src/sphinx_book_theme/header_buttons/__init__.py @@ -117,6 +117,7 @@ def add_header_buttons(app, pagename, templatename, context, doctree): "tooltip": translation("Fullscreen mode"), "icon": "fas fa-expand", "label": "fullscreen-button", + "classes": "pst-navbar-icon", } ) diff --git a/src/sphinx_book_theme/theme/sphinx_book_theme/components/page-toc.html b/src/sphinx_book_theme/theme/sphinx_book_theme/components/page-toc.html index e0dbff434..1589f71d3 100644 --- a/src/sphinx_book_theme/theme/sphinx_book_theme/components/page-toc.html +++ b/src/sphinx_book_theme/theme/sphinx_book_theme/components/page-toc.html @@ -6,10 +6,13 @@ -#} {% set page_toc = generate_toc_html() %} {%- if page_toc | length >= 1 %} -
+{%- set page_navigation_heading_id = unique_html_id("pst-page-navigation-heading") -%} +
{{ translate(theme_toc_title) }}
-
- - - + + diff --git a/tests/test_build/build__pagetoc--page-multipletitles.html b/tests/test_build/build__pagetoc--page-multipletitles.html index be65805e2..5a02f2ea1 100644 --- a/tests/test_build/build__pagetoc--page-multipletitles.html +++ b/tests/test_build/build__pagetoc--page-multipletitles.html @@ -1,12 +1,12 @@ -
+
-
+
Contents
-
- - - + +
diff --git a/tests/test_build/header__repo-buttons--custom-branch.html b/tests/test_build/header__repo-buttons--custom-branch.html index 56bd884e3..208a689c5 100644 --- a/tests/test_build/header__repo-buttons--custom-branch.html +++ b/tests/test_build/header__repo-buttons--custom-branch.html @@ -55,28 +55,24 @@
- - - + + diff --git a/tests/test_build/header__repo-buttons--one-on.html b/tests/test_build/header__repo-buttons--one-on.html index cf45b8dca..ec34bab2e 100644 --- a/tests/test_build/header__repo-buttons--one-on.html +++ b/tests/test_build/header__repo-buttons--one-on.html @@ -37,28 +37,24 @@ - - - + + diff --git a/tests/test_build/test_right_sidebar_title.html b/tests/test_build/test_right_sidebar_title.html index 7c1d278bb..0c251de5b 100644 --- a/tests/test_build/test_right_sidebar_title.html +++ b/tests/test_build/test_right_sidebar_title.html @@ -1,4 +1,4 @@ -
+
My test content title diff --git a/tox.ini b/tox.ini index 10492c43a..c334d0ee5 100644 --- a/tox.ini +++ b/tox.ini @@ -11,13 +11,13 @@ # then then deleting compiled files has been found to fix it: `find . -name \*.pyc -delete` [tox] -envlist = py310-sphinx6 +envlist = py313-sphinx8 [testenv] usedevelop=true passenv = TERM # To make terminal coloring / other variables pass through -[testenv:py{39,310,311}-pre-commit] +[testenv:py{311,312,313}-pre-commit] extras = code_style commands = pre-commit run {posargs} @@ -37,17 +37,32 @@ commands = clean: rm -rf docs/_build sphinx-build -n --keep-going -b {posargs:html} docs/ docs/_build/{posargs:html} +[testenv:docs-linkcheck] +extras = + doc +deps = + sphinx-theme-builder[cli] +commands = + sphinx-build -b linkcheck docs docs/_build/linkcheck + [testenv:docs-live] +usedevelop = true extras = doc deps = sphinx-theme-builder[cli] + sphinx-autobuild commands = - stb serve docs --open-browser + sphinx-autobuild docs docs/_build/html --open-browser \ + --watch src/sphinx_book_theme/assets \ + --watch src/sphinx_book_theme/theme \ + --ignore "docs/_build/*" \ + --re-ignore ".*\.pyc" \ + --re-ignore ".*~" -[testenv:py{39,310,311}-sphinx{5,6}] +[testenv:py{311,312,313}-sphinx{7,8}] extras = test deps = - sphinx5: sphinx>=5,<6 - sphinx6: sphinx>=6,<7 + sphinx7: sphinx>=7,<8 + sphinx8: sphinx>=8,<9 commands = pytest {posargs}