MAINT: Remove duplication with pydata-sphinx-theme (#640)

* Removing cruft for pydata theme

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Fixing tox

* typo

* bd article p-r-2

* footer and secondary sidebar

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* had to add _footer-content.scss, as pydata does not have any style

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* had to add _footer-content.scss, as pydata does not have any style

* hide the header btn on wide screens

* bd-main flex-grow is not necessary in sbt

* removing unnecessary style/mixins and adding some

* adding noqa

* removing unnecessary class and editing sidebar secondary option

* removing sidebar secondary buttons

* hiding source link

* pydata version

* span.sidenote and span.marginnote z-index

* citation style

* google link

* dependency changes

* file changes

* no print for sidebar secondary

* adding sphinx 4,5 in tox and secondary sidebar now won't show up when no headings present

* deprecating single_page, extra navbar, navbar_footer_text html options

* execution_show_tb to nb_execution_show_tb

* table style

* urlib.parse warning and custom-footer link removal

* images with fixed height/width

* search page style and fading of primary sidebar

* code block margin and show-inpage-toc

* margin content pushes code cells down

* output tag style

* announcemnet color

* search page style

* extension added for syntax highlighting

* Update src/sphinx_book_theme/assets/styles/components/_search.scss

Co-authored-by: Chris Holdgraf <[email protected]>

* ipython version

* checking if ipython version is the issue

* removing pygments_lexer metadata in test file

* jupyter logo

* logo img link

* adding deprecation for single page

* adding deprecation for single page

* removing border bottom for margins

* margin and sidebar styles

* font sizes for primary sidebar

* relaxing lighthouse score

* scrollbar mixin and animation

* responsive css and nav scroll attempt

* Remove buttons and responsive behavior fixes

* Cleaning up margin behavior

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Changelog error

* Fix tests

* More test fixes

* Move install to pyproject

* Pinning to latest release of pydata theme

* flex-basis primary-sidebar

* search text

* menu dropdown css

* alignment of buttons

* sidebar and margin fixes

* Tweaking two items

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: AakashGC <[email protected]>

Author: 3 people

.github/workflows/lighthouserc.json

@@ -9,9 +9,9 @@
     },
     "assert": {
       "assertions": {
-        "categories:performance": ["error", { "minScore": 0.85 }],
-        "categories:accessibility": ["error", { "minScore": 0.85 }],
-        "categories:best-practices": ["error", { "minScore": 0.85 }]
+        "categories:performance": ["error", { "minScore": 0.84 }],
+        "categories:accessibility": ["error", { "minScore": 0.84 }],
+        "categories:best-practices": ["error", { "minScore": 0.84 }]
       }
     }
   }

docs/conf.py

@@ -97,7 +97,7 @@
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
 html_css_files = ["custom.css"]
-jupyter_execute_notebooks = "cache"
+nb_execution_mode = "cache"
 thebe_config = {
     "repository_url": "https://github.com/binder-examples/jupyter-stacks-datascience",
     "repository_branch": "master",
@@ -129,9 +129,7 @@
     # For testing
     # "use_fullscreen_button": False,
     # "home_page_in_toc": True,
-    # "single_page": True,
     # "extra_footer": "<a href='https://google.com'>Test</a>",  # DEPRECATED KEY
-    # "extra_navbar": "<a href='https://google.com'>Test</a>",
     # "show_navbar_depth": 2,
 }
 
@@ -142,12 +140,12 @@
 fontawesome_included = True
 post_auto_image = 1
 post_auto_excerpt = 2
-execution_show_tb = "READTHEDOCS" in os.environ
+nb_execution_show_tb = "READTHEDOCS" in os.environ
 bibtex_bibfiles = ["references.bib"]
 # To test that style looks good with common bibtex config
 bibtex_reference_style = "author_year"
 bibtex_default_style = "plain"
-
+numpydoc_show_class_members = False  # for automodule:: urllib.parse stub file issue
 linkcheck_ignore = [
     "http://someurl/release",  # This is a fake link
     "https://doi.org",  # These don't resolve properly and cause SSL issues

docs/customize/footer-content.md

@@ -0,0 +1,26 @@
+# Customize the content footer
+
+There is a content footer that spans the width of the page, and is visibile when you scroll to the bottom of the content.
+
+By default, the content footer has the following items:
+
+- `author.html`: Display the author of the page, if present.
+- `copyright.html`: Display copyright information about the website.
+- `last-updated.html`: Display the latest date that the website was updated.
+- `extra-footer.html`: A placeholder for arbitrary HTML you may add (see [](content-footer:extra-footer)).
+
+(content-footer:extra-footer)=
+## Add extra HTML to your content footer
+
+You may add custom HTML to the content footer via `conf.py`.
+This is a shortcut in case you wish to avoid defining your own HTML template.
+
+To do so, use the `extra_footer` configuration and provide any HTML that you wish.
+For example:
+
+```python
+html_theme_options = {
+    ...
+    "extra_footer": "<div>hi there!</div>",
+}
+```

docs/customize/index.md

@@ -12,9 +12,6 @@ The following options are available via `html_theme_options`
 * - Key
   - Type
   - Description
-* - `single_page`
-  - bool
-  - Remove the left sidebar and treat the site as a single page. See [](customize:single-page).
 * - `path_to_docs`
   - string
   - Path to the documentation, relative to the repository root (e.g. `docs/`). See [](customize:source-files).
@@ -48,9 +45,6 @@ The following options are available via `html_theme_options`
 * - `show_navbar_depth`
   - int
   - Show children in the navigation bar down to the depth listed here. See [](sidebar:navbar-depth).
-* - `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.
@@ -66,10 +60,10 @@ The following sections describe a few ways to customize the theme in more depth.
 ```{toctree}
 sidebar-primary.md
 sidebar-secondary.md
+footer-content.md
 announcements.md
 header.md
 download.md
 source-files.md
 custom-css.md
-single-page.md
 ```

docs/customize/sidebar-primary.md

@@ -36,22 +36,6 @@ By default, this theme comes with these three theme-specific sidebar elements en
 - `sidebar-logo.html`: Displays the logo and site title.
 - `search-field.html`: A bootstrap-based search bar (from the [PyData Sphinx Theme](https://pydata-sphinx-theme.readthedocs.io/))
 - `sbt-sidebar-nav.html`: A bootstrap-based navigation menu for your book.
-- `sbt-sidebar-footer`: A [configurable](custom-footer) snippet of HTML to add to the sidebar (by default it is placed at the bottom).
-
-(custom-footer)=
-## Customize the sidebar footer
-
-You may choose your own HTML to include in the footer of your sidebar (or set it to be empty). To do so, set the following option in `conf.py`:
-
-```python
-html_theme_options = {
-    ...
-    "extra_navbar": "<p>Your HTML</p>",
-    ...
-}
-```
-
-This text will be placed at the bottom of the sidebar by default.
 
 
 ## Add a header to your Table of Contents

docs/customize/single-page.md

@@ -218,7 +218,7 @@ how does it look?
 
 Markdown cell with images in sidebar
 
-<img src="https://upload.wikimedia.org/wikipedia/commons/thumb/3/38/Jupyter_logo.svg/883px-Jupyter_logo.svg.png" style="max-width:200px" />
+<img src="https://upload.wikimedia.org/wikipedia/commons/thumb/3/38/Jupyter_logo.svg/883px-Jupyter_logo.svg.png" />
 
 ````
 +++

docs/reference/special-theme-elements.md

@@ -23,7 +23,7 @@ readme = "README.md"
 requires-python = ">=3.7"
 dependencies = [
   "sphinx>=4,<6",
-  "pydata-sphinx-theme~=0.10.1",
+  "pydata-sphinx-theme~=0.12.0",
   "pyyaml",
 ]
 
@@ -53,11 +53,11 @@ doc = [
     "numpy",
     "matplotlib",
     "numpydoc",
-    "myst-nb~=0.13.2",
+    "myst-nb~=0.16.0",
     "nbclient",
     "pandas",
     "plotly",
-    "sphinx~=4.0",
+    "sphinx>=4.0,<6",
     "sphinx-design",
     "sphinx-examples",
     "sphinx-copybutton",
@@ -67,11 +67,14 @@ doc = [
     "sphinxcontrib-bibtex~=2.2",
     "sphinxcontrib-youtube",
     "sphinxext-opengraph",
+    # 8.7.0 broke the `ipython3` lexer in Sphinx so we want to avoid it
+    # remove this when 8.7.1 is released (and see below for another instance)
+    "ipython!=8.7.0",
 ]
 test = [
     "beautifulsoup4>=4.6.1,<5",
     "coverage",
-    "myst-nb~=0.13.2",
+    "myst-nb~=0.16.0",
     "pytest~=7.1",
     "pytest-cov>=3,<5",
     "pytest-regressions>=2.0.1,<2.5.0",

pyproject.toml

@@ -19,6 +19,7 @@
 """sphinx-book-theme version"""
 
 SPHINX_LOGGER = logging.getLogger(__name__)
+DEFAULT_LOG_TYPE = "sphinxbooktheme"
 MESSAGE_CATALOG_NAME = "booktheme"
 
 
@@ -59,7 +60,7 @@ def add_metadata_to_page(app, pagename, templatename, context, doctree):
     context["translate"] = translation
     # this is set in the html_theme
     context["theme_search_bar_text"] = translation(
-        context.get("theme_search_bar_text", "Search the docs ...")
+        context.get("theme_search_bar_text", "Search...")
     )
 
 
@@ -151,6 +152,19 @@ def update_mode_thebe_config(app):
     app.config.html_context["default_mode"] = "light"
 
 
+def check_deprecation_keys(app):
+    """Warns about the deprecated keys."""
+
+    deprecated_config_list = ["single_page"]
+    for key in deprecated_config_list:
+        if key in app.env.config.html_theme_options:
+            SPHINX_LOGGER.warning(
+                f"'{key}' was deprecated from version 0.3.4 onwards. See the CHANGELOG for more information: https://github.com/executablebooks/sphinx-book-theme/blob/master/CHANGELOG.md"  # noqa: E501
+                f"[{DEFAULT_LOG_TYPE}]",
+                type=DEFAULT_LOG_TYPE,
+            )
+
+
 class Margin(Sidebar):
     """Goes in the margin to the right of the page."""
 
@@ -180,6 +194,28 @@ def update_general_config(app, config):
     config.templates_path.append(os.path.join(theme_dir, "components"))
 
 
+def update_templates(app, pagename, templatename, context, doctree):
+    """Update template names and assets for page build.
+
+    This is a copy of what the pydata theme does here to include a new section
+    - https://github.com/pydata/pydata-sphinx-theme/blob/0a4894fab49befc59eb497811949a1d0ede626eb/src/pydata_sphinx_theme/__init__.py#L173 # noqa: E501
+    """
+    # Allow for more flexibility in template names
+    template_sections = ["theme_footer_content_items"]
+    for section in template_sections:
+        if context.get(section):
+            # Break apart `,` separated strings so we can use , in the defaults
+            if isinstance(context.get(section), str):
+                context[section] = [
+                    ii.strip() for ii in context.get(section).split(",")
+                ]
+
+            # Add `.html` to templates with no suffix
+            for ii, template in enumerate(context.get(section)):
+                if not os.path.splitext(template)[1]:
+                    context[section][ii] = template + ".html"
+
+
 def setup(app: Sphinx):
     # Register theme
     theme_dir = get_html_theme_path()
@@ -192,9 +228,11 @@ def setup(app: Sphinx):
 
     # Events
     app.connect("builder-inited", update_mode_thebe_config)
+    app.connect("builder-inited", check_deprecation_keys)
     app.connect("config-inited", update_general_config)
     app.connect("html-page-context", add_metadata_to_page)
     app.connect("html-page-context", hash_html_assets)
+    app.connect("html-page-context", update_templates)
 
     # Nodes
     SideNoteNode.add_node(app)

src/sphinx_book_theme/__init__.py

@@ -3,7 +3,6 @@
 from docutils import nodes as docutil_nodes
 from sphinx import addnodes as sphinx_nodes
 from .nodes import SideNoteNode
-import copy
 
 
 class HandleFootnoteTransform(SphinxPostTransform):
@@ -64,7 +63,7 @@ def run(self, **kwargs: Any) -> None:
                     # so it works w/ margin. Only show one or another depending on
                     # screen width.
                     node_parent = ref_node.parent
-                    para_dup = copy.deepcopy(para)
+                    para_dup = para.deepcopy()
                     # looping to check parent node
                     while not isinstance(
                         node_parent, (docutil_nodes.section, sphinx_nodes.document)

src/sphinx_book_theme/_transforms.py

@@ -97,9 +97,9 @@ var initTocHide = () => {
 
     // Hide the TOC if any margin content is displayed on the screen
     if (onScreenItems.length > 0) {
-      $("div.bd-sidebar-secondary").removeClass("show");
+      $("div.bd-sidebar-secondary").addClass("hide");
     } else {
-      $("div.bd-sidebar-secondary").addClass("show");
+      $("div.bd-sidebar-secondary").removeClass("hide");
     }
   };
   let manageScrolledClassOnBody = (entries, observer) => {
@@ -159,50 +159,13 @@ var initThebeSBT = () => {
   initThebe();
 };
 
-/**
- * Use Bootstrap helper function to enable tooltips.
- */
-var initTooltips = () => {
-  $(document).ready(function () {
-    $('[data-toggle="tooltip"]').tooltip({
-      trigger: "hover",
-      delay: { show: 500, hide: 100 },
-    });
-  });
-};
-
-/**
- * MutationObserver to move the ReadTheDocs button
- */
-function initRTDObserver() {
-  const mutatedCallback = (mutationList, observer) => {
-    mutationList.forEach((mutation) => {
-      // Check whether the mutation is for RTD, which will have a specific structure
-      if (mutation.addedNodes.length === 0) {
-        return;
-      }
-      if (mutation.addedNodes[0].data === undefined) {
-        return;
-      }
-      if (mutation.addedNodes[0].data.search("Inserted RTD Footer") != -1) {
-        mutation.addedNodes.forEach((node) => {
-          document.getElementById("rtd-footer-container").append(node);
-        });
-      }
-    });
-  };
-
-  const observer = new MutationObserver(mutatedCallback);
-  const config = { childList: true };
-  observer.observe(document.body, config);
-}
-
 /**
  * Add no print class to certain DOM elements
  */
 
 function addNoPrint() {
   $("div.bd-sidebar-primary").addClass("noprint");
+  $("div.bd-sidebar-secondary").addClass("noprint");
   $("div.bd-header-article").addClass("noprint");
   $("div.bd-header-announcement").addClass("noprint");
   $("footer.bd-footer-article").addClass("noprint");
@@ -228,8 +191,6 @@ window.toggleFullScreen = toggleFullScreen;
 /**
  * Set up functions to load when the DOM is ready
  */
-sbRunWhenDOMLoaded(initTooltips);
 sbRunWhenDOMLoaded(initTocHide);
-sbRunWhenDOMLoaded(initRTDObserver);
 sbRunWhenDOMLoaded(addNoPrint);
 sbRunWhenDOMLoaded(setMode);