Merge branch 'master' into sphinx-7

.github/workflows/publish.yml

@@ -15,11 +15,11 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout source
-        uses: actions/checkout@v3
-      - name: Set up Python 3.9
+        uses: actions/checkout@v4
+      - name: Set up Python 3.11
         uses: actions/setup-python@v4
         with:
-          python-version: 3.9
+          python-version: 3.11
 
       - name: Build package
         run: |
@@ -28,7 +28,7 @@ jobs:
           python -m build
 
       - name: Publish
-        uses: pypa/[email protected].4
+        uses: pypa/[email protected].10
         with:
           user: __token__
           password: ${{ secrets.PYPI_KEY }}

.github/workflows/tests.yml

@@ -16,32 +16,34 @@ 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.11
     - uses: pre-commit/[email protected]
 
   tests:
     strategy:
       fail-fast: false
       matrix:
         os: [ubuntu-latest]
-        python-version: ["3.8", "3.9", "3.10", "3.11"]
+        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","~=6.0","~=7.0"]
         include:
         - os: windows-latest
-          python-version: "3.9"
-          sphinx: "~=6.0"
+          python-version: 3.11
+          sphinx: ">=6,<7"
         - os: macos-latest
-          python-version: "3.9"
-          sphinx: "~=6.0"
+          python-version: 3.11
+          sphinx: ">=6,<7"
     runs-on: ${{ matrix.os }}
 
     steps:
-    - uses: actions/checkout@v3
-    - name: Set up Python ${{ matrix.python-version }}
+    - uses: actions/checkout@v4
+    - name: Set up Python ${{ matrix.python-version }} and Sphinx ${{ matrix.sphinx }}
       uses: actions/setup-python@v4
       with:
         python-version: ${{ matrix.python-version }}
@@ -76,6 +78,7 @@ jobs:
       run: >
         pytest --cov=sphinx_book_theme --cov-report=xml --cov-report=term-missing
     - name: Upload to Codecov
+      if: matrix.os == 'ubuntu-latest' && matrix.python-version == 3.9 && github.repository == 'executablebooks/sphinx-book-theme' && github.event_name == 'pull_request'
       uses: codecov/codecov-action@v3
       with:
         name: pytests
@@ -86,11 +89,11 @@ jobs:
     runs-on: ubuntu-latest
     name: Build and Audit Documentation
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Set up Python
       uses: actions/setup-python@v4
       with:
-        python-version: '3.7'
+        python-version: '3.9'
         cache: "pip"
         cache-dependency-path: "pyproject.toml"
     - name: Install dependencies

.pre-commit-config.yaml

@@ -14,7 +14,7 @@ default_language_version:
 repos:
 
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.4.0
+    rev: v4.5.0
     hooks:
     - id: check-toml
     - id: check-json
@@ -23,17 +23,17 @@ repos:
     - id: trailing-whitespace
 
   - repo: https://github.com/PyCQA/flake8
-    rev: 6.0.0
+    rev: 6.1.0
     hooks:
     - id: flake8
 
   - repo: https://github.com/psf/black
-    rev: 23.3.0
+    rev: 23.9.1
     hooks:
     - id: black
 
   - repo: https://github.com/pre-commit/mirrors-prettier
-    rev: v3.0.0-alpha.9-for-vscode
+    rev: v3.0.3
     hooks:
       - id: prettier
         types_or: [scss, javascript]

.readthedocs.yml

@@ -1,10 +1,15 @@
 version: 2
+# Set the OS, Python version and other tools you might need
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.10"
 
 python:
-  version: 3
   install:
     - method: pip
-      path: .[doc]
+      path: ".[doc]"
 
 sphinx:
   builder: html

docs/conf.py

@@ -86,11 +86,11 @@
     "reference/blog/*": [
         "navbar-logo.html",
         "search-field.html",
-        "postcard.html",
-        "recentposts.html",
-        "tagcloud.html",
-        "categories.html",
-        "archives.html",
+        "ablog/postcard.html",
+        "ablog/recentposts.html",
+        "ablog/tagcloud.html",
+        "ablog/categories.html",
+        "ablog/archives.html",
         "sbt-sidebar-nav.html",
     ]
 }

docs/reference.md

@@ -42,7 +42,16 @@ These are **in addition to** all of the {external:doc}`options available in the
   - Whether to put the home page in the Navigation Bar (at the top). See [](sidebar-primary:home-page).
 * - `show_navbar_depth`
   - int
-  - Show children in the navigation bar down to the depth listed here. See [](sidebar:navbar-depth).
+  - Show children in the navigation bar down to the depth listed here. See [](sidebar:show-navbar-depth).
+* - `max_navbar_depth`
+  - int
+  - The maximum number of levels to show in the navbar. See [](sidebar:max-navbar-depth). (4 is default)
+* - `collapse_navbar`
+  - bool
+  - Whether to collapse the navbar, stopping the tree from being expanded. See [](sidebar:max-navbar-depth), (False is default)
+* - `extra_navbar`
+  - str
+  - Extra HTML to add below the sidebar footer. See [](custom-footer).
 * - `extra_footer`
   - str
   - Extra HTML to add in the footer of each page.

docs/sections/footer.md

@@ -7,7 +7,7 @@ However, there are two configuration points where you can add items to your foot
 
 `html_theme_options["footer_start"]` accepts a list of HTML templates that will be placed at the beginning (left on most screens) of the footer.
 
-`html_theme_options["footer_start"]` accepts a list of HTML templates that will be placed at the end (right on most screens) of the footer.
+`html_theme_options["footer_end"]` accepts a list of HTML templates that will be placed at the end (right on most screens) of the footer.
 
 For example, the configuration below assumes there is a template at `_templates/test.html`.
 It adds the `_templates` folder to Sphinx's templates path, and adds the template to both the start and end section of the footer.

docs/sections/header.md

@@ -14,7 +14,7 @@ There are three configuration options you can use in `html_theme_options`:
 
 **`navbar_end`**: Adds components to the end of the header. **Moved to the sizebar on mobile**. Use this for extra social links or buttons.
 
-## An eample
+## An example
 
 For example, you can add a button to the header like so:
 

docs/sections/sidebar-primary.md

@@ -58,7 +58,7 @@ html_theme_options = {
 }
 ```
 
-(sidebar:navbar-depth)=
+(sidebar:show-navbar-depth)=
 ## Control the depth of the left sidebar lists to expand
 
 You can control the level of toc items in the left sidebar to remain expanded,
@@ -73,3 +73,36 @@ html_theme_options = {
 ```
 
 The default value is `1`, which shows only top-level sections of the documentation (and is used in this documentation).
+
+(sidebar:max-navbar-depth)=
+
+## Control the maximum depth of the left sidebar lists
+
+You can control the level of toc items included in the left sidebar,
+using the following configuration in `conf.py`:
+
+```python
+html_theme_options = {
+    ...
+    "max_navbar_depth": <level>,
+    ...
+}
+```
+
+The default value is `4`.
+
+(sidebar:collapse-navbar)=
+## Turn off expandable left sidebar lists
+
+You can turn off the sidebar expanding,
+using the following configuration in `conf.py`:
+
+```python
+html_theme_options = {
+    ...
+    "collapse_navbar": True,
+    ...
+}
+```
+
+The default value is `False`, which allows the navbar to be expanded.

pyproject.toml

@@ -20,10 +20,10 @@ description = "A clean book theme for scientific explanations and documentation
 dynamic = ["version"]
 readme = "README.md"
 
-requires-python = ">=3.8"
+requires-python = ">=3.9"
 dependencies = [
   "sphinx>=5.0",
-  "pydata-sphinx-theme>=0.13.3",
+  "pydata-sphinx-theme>=0.14",
 ]
 
 license = { file = "LICENSE" }
@@ -59,8 +59,7 @@ doc = [
     "sphinx-design",
     "sphinx-examples",
     "sphinx-copybutton",
-    "sphinx-tabs<=3.4.0", # sphinx-tabs 3.4.1 needs docutils >.17, which would conflict with our pin above
-    "docutils==0.17.1", # docutils 0.18, 0.19 need a patch fix https://sourceforge.net/p/docutils/patches/195/, un-pin when 0.20 is released
+    "sphinx-tabs",
     "sphinx-togglebutton",
     "sphinx-thebe",
     "sphinxcontrib-bibtex",

src/sphinx_book_theme/header_buttons/source.py

@@ -86,19 +86,23 @@ def add_source_buttons(app, pagename, templatename, context, doctree):
 
         if opts.get("use_issues_button"):
             repo_url, provider = get_repo_url(context)
-            if provider != "github":
-                LOGGER.warning(f"Open issue button not yet supported for {provider}")
-            else:
+            if provider in ("github", "gitlab"):
+                if provider == "github":
+                    url = f"{repo_url}/issues/new?title=Issue%20on%20page%20%2F{context['pagename']}.html&body=Your%20issue%20content%20here."  # noqa: E501
+                elif provider == "gitlab":
+                    url = f"{repo_url}/-/issues/new?issue[title]=Issue%20on%20page%20%2F{context['pagename']}.html&issue[description]=Your%20issue%20content%20here."  # noqa: E501
                 repo_buttons.append(
                     {
                         "type": "link",
-                        "url": f"{repo_url}/issues/new?title=Issue%20on%20page%20%2F{context['pagename']}.html&body=Your%20issue%20content%20here.",  # noqa: E501
+                        "url": url,
                         "text": translation("Open issue"),
                         "tooltip": translation("Open an issue"),
                         "icon": "fas fa-lightbulb",
                         "label": "source-issues-button",
                     }
                 )
+            else:
+                LOGGER.warning(f"Open issue button not yet supported for {provider}")
 
         # If we have multiple repo buttons enabled, add a group, otherwise just 1 button
         if len(repo_buttons) > 1:

src/sphinx_book_theme/theme/sphinx_book_theme/components/sbt-sidebar-nav.html

@@ -1,4 +1,4 @@
-<nav class="bd-links" id="bd-docs-nav" aria-label="Main">
+<nav class="bd-links bd-docs-nav" aria-label="Main">
     <div class="bd-toc-item navbar-nav active">
         {% if theme_home_page_in_toc == True %}
         {#- This mimicks the pydata theme list style so we can append an extra item at the top #}
@@ -15,10 +15,10 @@
         {{- generate_toctree_html(
             startdepth=0,
             kind="sidebar",
-            maxdepth=4,
-            collapse=False,
+            maxdepth=theme_max_navbar_depth|int,
+            collapse=theme_collapse_navbar|tobool,
             includehidden=True,
             titles_only=True,
-            show_nav_level=theme_show_navbar_depth) }}
+            show_nav_level=theme_show_navbar_depth|int) }}
     </div>
 </nav>

src/sphinx_book_theme/theme/sphinx_book_theme/theme.conf

@@ -39,6 +39,8 @@ navbar_persistent =
 # Primary sidebar behavior
 home_page_in_toc = False
 show_navbar_depth = 1
+max_navbar_depth = 4
+collapse_navbar = False
 
 # Footer at the bottom of the content
 extra_footer =

tests/test_build.py

@@ -91,7 +91,7 @@ def test_build_book(sphinx_build_factory, file_regression):
     # Navigation entries
     if sphinx_build.software_versions == ".sphinx4":
         # Sphinx 4 adds some aria labeling that isn't in sphinx3, so just test sphinx4
-        sidebar = index_html.find(attrs={"id": "bd-docs-nav"})
+        sidebar = index_html.find(attrs={"class": "bd-docs-nav"})
         file_regression.check(
             sidebar.prettify(),
             basename="build__sidebar-primary__nav",
@@ -101,7 +101,7 @@ def test_build_book(sphinx_build_factory, file_regression):
 
     # Check navbar numbering
     sidebar_ntbk = sphinx_build.html_tree("section1", "ntbk.html").find(
-        "nav", id="bd-docs-nav"
+        "nav", attrs={"class": "bd-docs-nav"}
     )
     # Pages and sub-pages should be numbered
     assert "1. Page 1" in str(sidebar_ntbk)
@@ -146,7 +146,9 @@ def test_navbar_options_home_page_in_toc(sphinx_build_factory):
     ).build(
         assert_pass=True
     )  # type: SphinxBuild
-    navbar = sphinx_build.html_tree("index.html").find("nav", id="bd-docs-nav")
+    navbar = sphinx_build.html_tree("index.html").find(
+        "nav", attrs={"class": "bd-docs-nav"}
+    )
     # double checks if the master_doc has the current class
     li = navbar.find("li", attrs={"class": "current"})
     assert "Index with code in title" in str(li)
@@ -215,7 +217,7 @@ def test_header_repository_buttons(
 def test_source_button_url(sphinx_build_factory, file_regression, provider, repo):
     """Test that source button URLs are properly constructed."""
     # All buttons on
-    use_issues = "github.com" in repo
+    use_issues = "github.com" in repo or "gitlab.com" in repo or provider == "gitlab"
     confoverrides = {
         "html_theme_options": {
             "repository_url": repo,

tests/test_build/build__header-article.html

@@ -108,17 +108,17 @@
      </button>
      <script>
       document.write(`
-  <button class="theme-switch-button btn btn-sm btn-outline-primary navbar-btn rounded-circle" title="light/dark" aria-label="light/dark" data-bs-placement="bottom" data-bs-toggle="tooltip">
-    <span class="theme-switch" data-mode="light"><i class="fa-solid fa-sun"></i></span>
-    <span class="theme-switch" data-mode="dark"><i class="fa-solid fa-moon"></i></span>
-    <span class="theme-switch" data-mode="auto"><i class="fa-solid fa-circle-half-stroke"></i></span>
+  <button class="btn btn-sm navbar-btn theme-switch-button" title="light/dark" aria-label="light/dark" data-bs-placement="bottom" data-bs-toggle="tooltip">
+    <span class="theme-switch nav-link" data-mode="light"><i class="fa-solid fa-sun fa-lg"></i></span>
+    <span class="theme-switch nav-link" data-mode="dark"><i class="fa-solid fa-moon fa-lg"></i></span>
+    <span class="theme-switch nav-link" data-mode="auto"><i class="fa-solid fa-circle-half-stroke fa-lg"></i></span>
   </button>
 `);
      </script>
      <script>
       document.write(`
   <button class="btn btn-sm navbar-btn search-button search-button__button" title="Search" aria-label="Search" data-bs-placement="bottom" data-bs-toggle="tooltip">
-    <i class="fa-solid fa-magnifying-glass"></i>
+    <i class="fa-solid fa-magnifying-glass fa-lg"></i>
   </button>
 `);
      </script>

tests/test_build/header__repo-buttons--all-off.html

@@ -39,17 +39,17 @@
    </button>
    <script>
     document.write(`
-  <button class="theme-switch-button btn btn-sm btn-outline-primary navbar-btn rounded-circle" title="light/dark" aria-label="light/dark" data-bs-placement="bottom" data-bs-toggle="tooltip">
-    <span class="theme-switch" data-mode="light"><i class="fa-solid fa-sun"></i></span>
-    <span class="theme-switch" data-mode="dark"><i class="fa-solid fa-moon"></i></span>
-    <span class="theme-switch" data-mode="auto"><i class="fa-solid fa-circle-half-stroke"></i></span>
+  <button class="btn btn-sm navbar-btn theme-switch-button" title="light/dark" aria-label="light/dark" data-bs-placement="bottom" data-bs-toggle="tooltip">
+    <span class="theme-switch nav-link" data-mode="light"><i class="fa-solid fa-sun fa-lg"></i></span>
+    <span class="theme-switch nav-link" data-mode="dark"><i class="fa-solid fa-moon fa-lg"></i></span>
+    <span class="theme-switch nav-link" data-mode="auto"><i class="fa-solid fa-circle-half-stroke fa-lg"></i></span>
   </button>
 `);
    </script>
    <script>
     document.write(`
   <button class="btn btn-sm navbar-btn search-button search-button__button" title="Search" aria-label="Search" data-bs-placement="bottom" data-bs-toggle="tooltip">
-    <i class="fa-solid fa-magnifying-glass"></i>
+    <i class="fa-solid fa-magnifying-glass fa-lg"></i>
   </button>
 `);
    </script>