Sphinx 7 support

.github/workflows/tests.yml

@@ -2,7 +2,7 @@ name: continuous-integration
 
 on:
   push:
-    branches: [master]
+    branches: [main]
     tags:
       - 'v*'
   pull_request:
@@ -12,19 +12,21 @@ jobs:
   docs:
     runs-on: ubuntu-latest
     strategy:
+      fail-fast: false
       matrix:
-        python-version: [3.7, 3.8, 3.9]
+        python-version: ["3.7", "3.8", "3.9", "3.10", "3.11"]
+        sphinx: [ "~=4.0", "~=5.0", "~=6.0", "~=7.0" ]
 
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v1
+      uses: actions/setup-python@v4
       with:
         python-version: ${{ matrix.python-version }}
-    - name: Install dependencies
+    - name: Install sphinx-thebe with sphinx ${{ matrix.sphinx }}
       run: |
-        python -m pip install --upgrade pip
-        pip install -e .[sphinx,testing]
+        pip install --upgrade pip
+        pip install --upgrade "Sphinx${{ matrix.sphinx }}" -e .[testing]
     - name: Run tests
       run: |
         pytest

setup.py

@@ -47,15 +47,22 @@
         "Programming Language :: Python :: Implementation :: PyPy",
         "Topic :: Software Development :: Libraries :: Python Modules",
     ],
-    install_requires=["sphinx>=4,<7"],
+    install_requires=["sphinx>=4"],
     extras_require={
         "sphinx": [
-            "matplotlib",
             "myst-nb",
             "sphinx-book-theme>=0.4.0rc1",
             "sphinx-copybutton",
             "sphinx-design",
         ],
-        "testing": ["matplotlib", "pytest", "pytest-regressions", "beautifulsoup4"],
+        "testing": [
+            # TODO: Minimize the testing dependencies
+            "myst-parser",
+            "myst-nb",
+            "matplotlib",
+            "pytest",
+            "pytest-regressions",
+            "beautifulsoup4",
+        ],
     },
 )

tests/test_build.py

@@ -6,7 +6,7 @@
 
 
 path_tests = Path(__file__).parent.resolve()
-path_docs = path_tests.joinpath("..", "docs")
+path_docs = path_tests.joinpath("test_build", "src")
 
 
 @pytest.fixture(scope="session")
@@ -21,15 +21,10 @@ class SphinxBuild:
         path_pg_ntbk = path_html.joinpath("examples/notebooks.html")
         cmd_base = ["sphinx-build", ".", "_build/html", "-a", "-W"]
 
-        def copy(self, path=None):
+        def copy(self, path: Path = path_docs):
             """Copy the specified book to our tests folder for building."""
-            if path is None:
-                path = path_docs
-                path_changelog = path / "../CHANGELOG.md"
             if not self.path_tmp_docs.exists():
                 copytree(path, self.path_tmp_docs)
-                # Copy since it's loaded with an `include` directive
-                copy(path_changelog, self.path_tmp)
 
         def build(self, cmd=None):
             """Build the test book"""

tests/test_build/src/conf.py

@@ -0,0 +1,25 @@
+project = "Sphinx Thebe"
+copyright = "2020, Executable Book Project"
+author = "Executable Book Project"
+version = ""
+release = ""
+
+extensions = [
+    "myst_parser",
+    "sphinx_thebe",
+    "myst_nb",
+]
+
+thebe_config = {
+    "repository_url": "https://github.com/binder-examples/jupyter-stacks-datascience",
+    "path_to_docs": "docs",
+}
+
+myst_enable_extensions = ["colon_fence"]
+source_suffix = [".rst", ".md"]
+
+exclude_patterns = [
+    "_build",
+    "Thumbs.db",
+    ".DS_Store",
+]

tests/test_build/src/configure.md

@@ -0,0 +1,192 @@
+---
+thebe-kernel: ir
+---
+
+# Configuration
+
+(configure:selector)=
+## Change the HTML selector to mark interactive cells
+
+By default, `sphinx-thebe` will be run on any cells with the `thebe` class.
+However, you can customize the HTML selector to use other classes, elements, etc.
+
+For example, if you wanted to convert **all code cells**, you could use the following
+selector:
+
+```python
+thebe_config = {
+   "selector": "div.highlight"
+}
+```
+
+```{note}
+`sphinx-thebe` will subsequently look for any `pre` blocks inside of elements it
+finds with the `selector` configuration value. These are the blocks that will be
+converted to interactive with `thebe`.
+```
+
+## Including outputs with your code
+
+If you'd like to include outputs in the *static* version of your page, and only
+overwrite them once the user has run that Thebe cell, you can configure `sphinx-thebe`
+to detect and keep the outputs associated with some code. To do so, use
+the `selector_output` configuration. This is a selector that is searched for *within* any
+items discovered by `selector`. If an output is found, it will be placed just after the
+code and Thebe will detect it.
+
+For example, the following code:
+
+Defines a *parent container* in which we'll put both code and the output of the
+code. We'll use a `code-block` for the code, and another `container` node with our
+`output` class for the output. `sphinx-gallery` will detect the parent container because
+it has a `thebe` class. It will detect the `pre` block inside the container as the
+code, and it will detect the `<div>` block with the `output` class as the output.
+
+The result is that initializing Thebe *retains* the output until the cell is
+executed, like so:
+
+```{thebe-button}
+```
+
+````{container} thebe
+```{code-block} r
+print("hi")
+```
+
+```{container} output
+"hi"
+```
+````
+
+## Setting the Kernel
+
+You can set the kernel that Thebe uses on a page by adding metadata to your
+page. To do so, add the following metadata to the top of your page:
+
+```
+thebe-kernel: <kernel-name>
+```
+
+For example, this page had the following metadata in it:
+
+```
+thebe-kernel: ir
+```
+
+In addition, this website is configured to use the [Binder R example repository](https://github.com/binder-examples/r)
+for its environment. As a result, we can now run R code interactively with Thebe:
+
+
+```{thebe-button} Launch thebe in R
+```
+
+```{code-block}
+:class: thebe, thebe-init
+# Load ggplot - this will be automatically-run
+library(ggplot2)
+```
+
+```{code-block}
+:class: thebe, thebe-init
+# create factors with value labels
+mtcars$gear <- factor(mtcars$gear,levels=c(3,4,5),
+  	labels=c("3gears","4gears","5gears"))
+mtcars$am <- factor(mtcars$am,levels=c(0,1),
+  	labels=c("Automatic","Manual"))
+mtcars$cyl <- factor(mtcars$cyl,levels=c(4,6,8),
+   labels=c("4cyl","6cyl","8cyl"))
+```
+
+```{code-block}
+:class: thebe, thebe-init
+# Kernel density plots for mpg
+# grouped by number of gears (indicated by color)
+qplot(mpg, data=mtcars, geom="density", fill=gear, alpha=I(.5),
+   main="Distribution of Gas Milage", xlab="Miles Per Gallon",
+   ylab="Density")
+```
+
+```{code-block}
+:class: thebe
+
+# Scatterplot of mpg vs. hp for each combination of gears and cylinders
+# in each facet, transmittion type is represented by shape and color
+qplot(hp, mpg, data=mtcars, shape=am, color=am,
+   facets=gear~cyl, size=I(3),
+   xlab="Horsepower", ylab="Miles per Gallon")
+```
+
+## Automatically running some code
+
+You can tag code blocks to run as soon as the kernel is ready (i.e., without any user input)
+by adding the `thebe-init` class to the code blocks. For example:
+
+These code blocks will be run automatically once the kernel is ready, and their outputs
+will be displayed below.
+
+
+(add-custom-button)=
+## Adding your own button to start Thebe
+
+By default, Thebe encourages users to use the `thebe-button` directive to
+insert a thebe button into their documentation. However, you can add your own
+buttons wherever you wish. Simply ensure that an HTML element has this attribute:
+
+```js
+onclick="initThebe()"
+```
+
+and it will be able to initialize Thebe on that page on its own.
+
+For example, here is the HTML for the Thebe button generated by the `thebe-button`
+directive:
+
+```html
+<button title="Make live" class="thebe-button" onclick="initThebe()">
+  Make live
+</button>
+```
+
+## Choose a codemirror theme
+
+You can customize `sphinx-thebe` to use the codemirror theme of your choice.
+To do so, use the following configuration:
+
+```python
+thebe_config = {
+   "codemirror-theme": "<cm-theme>"
+}
+```
+
+See [the CodeMirror theme demo](https://codemirror.net/demo/theme.html) for a list
+of themes that you can use, and what they look like.
+
+## Load `thebe` automatically on all pages
+
+By default, `sphinx-thebe` will lazily load the JS/CSS from `thebe` when the `sphinx-thebe` initialization button is pressed.
+This means that no Javascript is loaded until a person explicitly tries to start thebe, which reduces page load times.
+
+If you want `thebe` to be loaded on every page, in an "eager" fashion, you may do so with the following configuration:
+
+```python
+thebe_config = {
+   "always_load": True
+}
+```
+
+## Configuration reference
+
+Here's a reference of all of the configuration values avialable to `sphinx-thebe`.
+Many of these eventually make their was into the `thebe` configuration. You can
+find a [reference for `thebe` configuration here](https://thebe.readthedocs.io/en/latest/config_reference.html).
+
+```python
+thebe_config = {
+    "always_load": bool (default True)
+    "repository_url": "<your-repo-url>",
+    "repository_branch": "<your-repo-branch>",
+    "selector": "<selector-for-code-cells>",
+    "selector_input": "<selector-for-cell-input>",
+    "selector_output": "<selector-for-cell-output>",
+}
+```

tests/test_build/src/examples/notebooks.md

@@ -0,0 +1,59 @@
+---
+jupytext:
+  formats: md:myst
+  text_representation:
+    extension: .md
+    format_name: myst
+kernelspec:
+  display_name: Python 3
+  language: python
+  name: python3
+---
+
+# Jupyter Notebooks
+
+This page was written for [MyST-NB](https://myst-nb.readthedocs.io/).
+It demonstrates `sphinx-thebe`'s usage with Jupyter Notebooks.
+
+Activate Thebe by clicking the launch button below.
+You should then be able to run and edit the code cell in the notebook.
+
+```{thebe-button} Launch thebe
+```
+
+The outputs should be displayed below, but they will be collected by `sphinx-thebe` when it is activated so that they are cleared when you first run the cell.
+
+```{code-cell}
+import numpy as np
+import matplotlib.pyplot as plt
+
+# Create some fake data
+data = np.random.randn(3, 1000)
+
+# Create a figure
+fig, ax = plt.subplots()
+
+# Plot data
+ax.scatter(data[0], data[1], c=np.abs(data[2]), s=np.abs(data[2])*100)
+```
+
+## Code style
+
+Thebe uses CodeMirror in the background, which uses different styles than pygments, which is used for static code syntax highlighting.
+
+The below code block is **static** and will not be converted with `thebe`.
+We include it in order to compare the active Thebe cell's syntax highlighting with an inactive cell.
+
+```
+import numpy as np
+import matplotlib.pyplot as plt
+
+# Create some fake data
+data = np.random.randn(3, 1000)
+
+# Create a figure
+fig, ax = plt.subplots()
+
+# Plot data
+ax.scatter(data[0], data[1], c=np.abs(data[2]), s=np.abs(data[2])*100)
+```