sphinx-book-theme 1.1.4__tar.gz → 1.3.0.dev0__tar.gz

{sphinx_book_theme-1.1.4 → sphinx_book_theme-1.3.0.dev0}/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}

{sphinx_book_theme-1.1.4 → sphinx_book_theme-1.3.0.dev0}/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## v1.2.0 -- 2026-03-09
+
+* Jupyterlite button - patched, merged version of #655 by @matthew-brett in https://github.com/executablebooks/sphinx-book-theme/pull/914
+* [ENH] Show source text on GitLab projects by @tymcauley in https://github.com/executablebooks/sphinx-book-theme/pull/916
+* Fix typo in docs by @user27182 in https://github.com/executablebooks/sphinx-book-theme/pull/913
+* prepare for latest pydata and python releases by @choldgraf in https://github.com/executablebooks/sphinx-book-theme/pull/920
+* Ignore PendingDeprecationWarning about parser_name deprecation with Docutils 0.22 by @mitya57 in https://github.com/executablebooks/sphinx-book-theme/pull/919
+* CI: adding cronjob by @bsipocz in https://github.com/executablebooks/sphinx-book-theme/pull/926
+* DOC: Fix margin directive documentation by @melissawm in https://github.com/executablebooks/sphinx-book-theme/pull/930
+* MAINT: adding sphinx9 and python3.14 support and bumping minimum sphinx to 7 and python to 3.11 by @bsipocz in https://github.com/executablebooks/sphinx-book-theme/pull/927
+
+
+**Full Changelog**:
+https://github.com/executablebooks/sphinx-book-theme/compare/v1.1.4...v1.2
+
+
 ## v1.1.2 -- 2024-02-13
 
 ([full changelog](https://github.com/executablebooks/sphinx-book-theme/compare/v1.1.1...3da24da74f6042599fe6c9e2d612f5cbdef42280))

{sphinx_book_theme-1.1.4 → sphinx_book_theme-1.3.0.dev0}/PKG-INFO

@@ -1,38 +1,9 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: sphinx-book-theme
-Version: 1.1.4
+Version: 1.3.0.dev0
 Summary: A clean book theme for scientific explanations and documentation with Sphinx
 Maintainer-Email: Executable Books Team <executablebooks@gmail.com>
-License: BSD 3-Clause License
-         
-         Copyright (c) 2020, Chris Holdgraf
-         All rights reserved.
-         
-         Redistribution and use in source and binary forms, with or without
-         modification, are permitted provided that the following conditions are met:
-         
-         1. Redistributions of source code must retain the above copyright notice, this
-            list of conditions and the following disclaimer.
-         
-         2. Redistributions in binary form must reproduce the above copyright notice,
-            this list of conditions and the following disclaimer in the documentation
-            and/or other materials provided with the distribution.
-         
-         3. Neither the name of the copyright holder nor the names of its
-            contributors may be used to endorse or promote products derived from
-            this software without specific prior written permission.
-         
-         THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
-         AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-         IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-         DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
-         FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
-         DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
-         SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
-         CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
-         OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-         OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-         
+License-File: LICENSE
 Classifier: Development Status :: 4 - Beta
 Classifier: Programming Language :: Python :: 3
 Classifier: Framework :: Sphinx
@@ -41,13 +12,13 @@ Classifier: License :: OSI Approved :: BSD License
 Classifier: Operating System :: OS Independent
 Project-URL: Repository, https://github.com/executablebooks/sphinx-book-theme
 Project-URL: Documentation, https://sphinx-book-theme.readthedocs.io/
-Requires-Python: >=3.9
-Requires-Dist: sphinx>=6.1
-Requires-Dist: pydata-sphinx-theme==0.15.4
+Requires-Python: >=3.11
+Requires-Dist: sphinx>=7.0
+Requires-Dist: pydata-sphinx-theme==0.17.1
 Provides-Extra: code-style
 Requires-Dist: pre-commit; extra == "code-style"
 Provides-Extra: doc
-Requires-Dist: ablog; extra == "doc"
+Requires-Dist: ablog>=0.11.13; extra == "doc"
 Requires-Dist: ipywidgets; extra == "doc"
 Requires-Dist: folium; extra == "doc"
 Requires-Dist: numpy; extra == "doc"
@@ -81,6 +52,9 @@ Description-Content-Type: text/markdown
 
 [![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
@@ -121,7 +95,7 @@ theme. See the pages to the left for information about what you can configure wi
 See [the Sphinx Book Theme documentation](https://sphinx-book-theme.readthedocs.io/en/latest/)
 for more information.
 
-[codecov-badge]: https://codecov.io/gh/executablebooks/sphinx-book-theme/branch/master/graph/badge.svg
+[codecov-badge]: https://codecov.io/gh/executablebooks/sphinx-book-theme/branch/main/graph/badge.svg
 [codecov-link]: https://codecov.io/gh/executablebooks/sphinx-book-theme
 
 [rtd-badge]: https://readthedocs.org/projects/sphinx-book-theme/badge/?version=latest

{sphinx_book_theme-1.1.4 → sphinx_book_theme-1.3.0.dev0}/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
@@ -42,7 +45,7 @@ theme. See the pages to the left for information about what you can configure wi
 See [the Sphinx Book Theme documentation](https://sphinx-book-theme.readthedocs.io/en/latest/)
 for more information.
 
-[codecov-badge]: https://codecov.io/gh/executablebooks/sphinx-book-theme/branch/master/graph/badge.svg
+[codecov-badge]: https://codecov.io/gh/executablebooks/sphinx-book-theme/branch/main/graph/badge.svg
 [codecov-link]: https://codecov.io/gh/executablebooks/sphinx-book-theme
 
 [rtd-badge]: https://readthedocs.org/projects/sphinx-book-theme/badge/?version=latest

{sphinx_book_theme-1.1.4 → sphinx_book_theme-1.3.0.dev0}/docs/components/logo.md

@@ -5,4 +5,4 @@
 You can customize the logo, title, and favicon of your site.
 
 Refer to {external:doc}`the PyData Sphinx Theme branding documentation <user_guide/branding>` for how to customize the logo and title.
-This theme re-uses the same configuration.
+This theme reuses the same configuration.

{sphinx_book_theme-1.1.4 → sphinx_book_theme-1.3.0.dev0}/docs/components/source-files.md

@@ -48,7 +48,7 @@ Once this is provided, you may add source buttons by following the following sec
 (source-buttons:source)=
 ## Add a button to the page source
 
-Show the raw source of the page on the provider you've proivded.
+Show the raw source of the page on the provider you've provided.
 To add a button to the page source, first [configure your source repository](source-buttons:repository) and then add:
 
 ```python

{sphinx_book_theme-1.1.4 → sphinx_book_theme-1.3.0.dev0}/docs/conf.py

@@ -109,7 +109,8 @@ thebe_config = {
 html_theme_options = {
     "path_to_docs": "docs",
     "repository_url": "https://github.com/executablebooks/sphinx-book-theme",
-    "repository_branch": "master",
+    "repository_branch": "main",
+    "search_as_you_type": True,
     "launch_buttons": {
         "binderhub_url": "https://mybinder.org",
         "colab_url": "https://colab.research.google.com/",
@@ -190,6 +191,8 @@ numpydoc_show_class_members = False  # for automodule:: urllib.parse stub file i
 linkcheck_ignore = [
     "http://someurl/release",  # This is a fake link
     "https://doi.org",  # These don't resolve properly and cause SSL issues
+    "https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html",  # anchors throw a 403 forbidden error
+    "https://docutils.sourceforge.io/docs/ref/rst/directives.html",  # anchors throw a 403 forbidden error
 ]
 linkcheck_exclude_documents = ["changelog"]
 

{sphinx_book_theme-1.1.4 → sphinx_book_theme-1.3.0.dev0}/docs/content/content-blocks.md

@@ -141,10 +141,17 @@ If you'd like in-line margin content with numbered references, see [](margin:sid
 
 Here's how you can use the `{margin}` directive:
 
-````{example}
-:no-container:
-:reverse:
+```{margin} **Here is my margin content**
+It is pretty cool!
+```
+
+:::{important}
+The `{margin}` directive should not be nested under other elements such as topics or admonitions.
+:::
+
+**Source**
 
+````
 ```{margin} **Here is my margin content**
 It is pretty cool!
 ```
@@ -217,12 +224,17 @@ We can reference the figure with {ref}`myfig4`. Or a numbered reference like
 
 Margin content can include all kinds of things, such as code blocks:
 
+**Code blocks in the margin**
+
 ````{margin} Code blocks in margins
 ```python
 print("here is some python")
 ```
 ````
 
+**Source**
+
+`````
 ````{margin} Code blocks in margins
 ```python
 print("here is some python")
@@ -230,10 +242,18 @@ print("here is some python")
 ````
 `````
 
-`````{example} Admonitions and images in the margin
-:no-container:
-:reverse:
+**Admonitions and images in the margin**
 
+````{margin} **Notes in margins**
+```{note}
+Wow, a note with an image in a margin!
+![](../images/cool.jpg)
+```
+````
+
+**Source**
+
+`````
 ````{margin} **Notes in margins**
 ```{note}
 Wow, a note with an image in a margin!
@@ -249,9 +269,16 @@ page to flow around them, rather than moving to the right margin.
 
 To add content sidebars, use this syntax:
 
-`````{example}
-:no-container:
+````{sidebar} **My sidebar title**
+```{note}
+Here is my sidebar content, it is pretty cool!
+```
+![](../images/cool.jpg)
+````
 
+**Source**
+
+`````
 ````{sidebar} **My sidebar title**
 ```{note}
 Here is my sidebar content, it is pretty cool!
@@ -265,6 +292,10 @@ However, the sidebar text will still be in line with your content. There are
 certain kinds of elements, such as "note" blocks and code cells, that may
 clash with your sidebar. If this happens, try using a `{margin}` instead.
 
+:::{important}
+The `{sidebar}` directive should not be nested under other elements such as topics or admonitions.
+:::
+
 ## Full-width content
 
 Full-width content extends into the right margin, making it stand out against

{sphinx_book_theme-1.1.4 → sphinx_book_theme-1.3.0.dev0}/docs/content/launch.md

@@ -2,11 +2,13 @@
 # Launch buttons for interactivity
 
 You can automatically add buttons that allow users to interact with your
-book's content. This is either by directing them to a BinderHub or JupyterHub
-that runs in the cloud, or by making your page interactive using Thebe.
+book's content. This is can be by directing them to
+a [JupyterLite](https://jupyterlite.readthedocs.io) installation (that runs in
+the user's browser) or one of BinderHub or JupyterHub (that runs in the
+cloud), or by making your page interactive using Thebe.
 
-To use either Binder or JupyterHub links, you'll first need to configure your
-documentation's repository url:
+To use any of JupyterLite or Binder or JupyterHub links, you'll first need to
+configure your documentation's repository url:
 
 ```python
 html_theme_options = {
@@ -26,6 +28,28 @@ folder as your content, then Binder/JupyterHub links will point to the ipynb
 file instead of the text file.
 ```
 
+## JupyterLite
+
+If you are adding [JupyterLite](https://github.com/jupyterlite/jupyterlite) links to your page, first work out where your
+JupyterLite instance will be serving from, then add the URL to your
+configuration. In the example below, we've set up JupyterLite pages at the
+base URL of the main pages site, and at subdirectory `interact/lab`:
+
+```python
+html_theme_options = {
+    ...
+    "launch_buttons": {
+        "jupyterlite_url": "interact/lab/index.html"
+    },
+    ...
+}
+```
+
+See <https://odsti.github.io/cfd-textbook> for an example
+[JupyterBook](https://jupyterbook.org) project serving JupyterLite using this
+configuration, and <https://github.com/odsti/cfd-textbook> for the driving
+repository.
+
 ## Binder / BinderHub
 
 To add Binder links to your page, add the following configuration:

{sphinx_book_theme-1.1.4 → sphinx_book_theme-1.3.0.dev0}/docs/contributing/setup.md

@@ -39,17 +39,17 @@ Follow these steps:
    $ pre-commit install
    ```
 
-   :::{margin}
-   You can also run pre-commit via `tox`:
-   ```console
-   $ tox -e py38-pre-commit -- --all
-   ```
-   or manually run all `pre-commit` jobs for this repository:
+:::{margin}
+You can also run pre-commit via `tox`:
+```console
+$ tox -e py38-pre-commit -- --all
+```
+or manually run all `pre-commit` jobs for this repository:
 
-   ```console
-   $ pre-commit run --all-files
-   ```
-   :::
+```console
+$ pre-commit run --all-files
+```
+:::
 
 The rest of these instructions use `tox` to automate the installation and commands necessary to do many common things.
 

{sphinx_book_theme-1.1.4 → sphinx_book_theme-1.3.0.dev0}/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.12, Sphinx 8
+$ tox -e py312-sphinx8
 ```
 
 ## 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 py312-sphinx8
 ```
 
 ## 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 7-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
 ```
 

{sphinx_book_theme-1.1.4 → sphinx_book_theme-1.3.0.dev0}/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.
+:::