You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This is a minor release to conditionally load the JS on pages that have a "launch button".
17
+
This will save some load time on non-interactive pages.
18
+
19
+
### Enhancements made
20
+
21
+
- Option to conditionally load on pages, see [documentation for details](https://sphinx-thebe.readthedocs.io/en/latest/configure.html#only-load-js-on-certain-pages)[#30](https://github.com/executablebooks/sphinx-thebe/pull/30) ([@choldgraf](https://github.com/choldgraf))
This is a minor release to conditionally load the JS on pages that have a "launch button".
8
-
This will save some load time on non-interactive pages.
9
-
10
-
### Enhancements made
11
-
12
-
- Option to conditionally load on pages, see [documentation for details](https://sphinx-thebe.readthedocs.io/en/latest/configure.html#only-load-js-on-certain-pages)[#30](https://github.com/executablebooks/sphinx-thebe/pull/30) ([@choldgraf](https://github.com/choldgraf))
Copy file name to clipboardExpand all lines: docs/contribute.md
+17-1Lines changed: 17 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,7 +1,16 @@
1
-
# Contributing to Sphinx-Thebe
1
+
# Contribute to `sphinx-thebe`
2
2
3
3
Thanks for your interest in contributing to `sphinx-thebe`, your contributions are welcome and appreciated 🎉. This page contains some information to help you get started.
4
4
5
+
## Design philosophy
6
+
7
+
`sphinx-thebe` is designed to be a simple bridge between Sphinx and `thebe`.
8
+
It should not add a lot of extra functionality on top of Thebe, beyond special-casing its configuration for Sphinx objects and its build system.
9
+
It's primary goal is to make it pain-free to load `thebe.js` and apply it to websites generated by Sphinx with reasonable default choices.
10
+
11
+
`sphinx-thebe` adds default configuration to support major Jupyter Notebook extensions in the Sphinx ecosystem.
12
+
Currently this means [MyST-NB](https://myst-nb.readthedocs.io/), but in the future we'd also like to support [nbsphinx](https://nbsphinx.readthedocs.io/) by default.
13
+
5
14
## Contributing guide
6
15
7
16
See the [ExecutableBooks developer guidelines](https://executablebooks.org/en/latest/contributing.html) for conventions and practices around developing `sphinx-thebe`.
@@ -14,6 +23,13 @@ See the [ExecutableBooks developer guidelines](https://executablebooks.org/en/la
14
23
- The sphinx package is contained in `sphinx_thebe/`. The `__init__.py` file contains the code that activates and loads the proper CSS and JS when Sphinx is run.
15
24
- CSS and Javascript assets are in `sphinx_thebe/_static`. These handle the activation of `thebe` on a page via a button-click, and also make minor modification to the page's DOM to make it work well with `thebe`.
16
25
26
+
## Code style
27
+
28
+
The JavaScript and CSS assets for this repository follow the default values for [prettier](https://prettier.io/).
29
+
30
+
Python code follows `black` and `pep8` as described in [the EBP contributing guide](https://executablebooks.org/en/latest/contributing.html#coding-style).
31
+
32
+
17
33
## Installation for development
18
34
19
35
To install `sphinx-thebe` for development clone and install `sphinx-thebe` locally:
This page was written for [MyST-NB](https://myst-nb.readthedocs.io/).
16
+
It demonstrates `sphinx-thebe`'s usage with Jupyter Notebooks.
17
+
18
+
Activate Thebe by clicking the launch button below.
19
+
You should then be able to run and edit the code cell in the notebook.
20
+
21
+
```{thebe-button} Launch thebe
22
+
```
23
+
24
+
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.
Copy file name to clipboardExpand all lines: docs/index.md
+4-7Lines changed: 4 additions & 7 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -13,6 +13,8 @@
13
13
14
14
Make your code cells interactive with a kernel provided by [Thebe](http://thebe.readthedocs.org/) and [Binder](https://mybinder.org).
15
15
16
+
It uses the excellent [thebe project](http://thebe.readthedocs.org/), and pre-configures `thebe` to be compatible with common Jupyter-related patterns in the Sphinx ecosystem, such as [MyST-NB](https://myst-nb.readthedocs.io/).
17
+
16
18
For example, click the button below. Notice that the code block beneath becomes
17
19
editable and runnable!
18
20
@@ -27,15 +29,10 @@ print("hi")
27
29
28
30
See [](use.md) for more information about what you can do with `sphinx-thebe`.
29
31
30
-
```{note}
31
-
This package is a Sphinx wrapper around the excellent [thebe project](http://thebe.readthedocs.org/),
32
-
a javascript tool to convert static code cells into interactive cells backed
33
-
by a kernel.
34
-
```
35
32
36
33
## Install
37
34
38
-
To install `sphinx-thebe` first clonse and install it:
35
+
To install `sphinx-thebe` first clone and install it:
39
36
40
37
```
41
38
pip install sphinx-thebe
@@ -61,7 +58,7 @@ For more information on using `sphinx-thebe`, see [](use.md).
Copy file name to clipboardExpand all lines: docs/use.md
+71-27Lines changed: 71 additions & 27 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,16 +1,15 @@
1
-
# Using `sphinx-thebe`
1
+
# Use `sphinx-thebe`
2
+
3
+
`sphinx-thebe` uses remote Jupyter kernels to execute your page's code and return the
4
+
results, and [Binder](https://mybinder.org) to run the infrastructure for execution.
5
+
You can do nearly anything with `sphinx-thebe` that you could do from within a Jupyter Notebook cell.
2
6
3
7
## Get started
4
8
5
9
There are two steps to using `sphinx-thebe`. First, you must mark certain
6
10
parts of your page as "ready for thebe". Next, you must insert a button onto
7
11
the page to tell Thebe to initialize.
8
12
9
-
:::{admonition} Using reStructuredText vs. MyST Markdown
10
-
:class: tip
11
-
The examples on this page use **MyST Markdown syntax**, a form of markdown that works with Sphinx directives. You can also use reStructuredText if you wish. For information about reStructuredText vs. MyST Markdown, see [the MyST Parser documentation](https://myst-parser.readthedocs.io/en/latest/using/syntax.html) as well as [](examples/rst) for some tips.
12
-
:::
13
-
14
13
### Mark elements for thebe
15
14
16
15
By default, thebe will be run on any elements in your documentation that contain
@@ -19,8 +18,9 @@ the class `thebe` and that have a `<pre`> element underneath them.
19
18
You can add code blocks like so:
20
19
21
20
````
22
-
```{code-block}
21
+
```{code-block} python
23
22
:class: thebe
23
+
print("hello world!")
24
24
```
25
25
````
26
26
@@ -37,36 +37,34 @@ directive:
37
37
```
38
38
````
39
39
40
-
The button looks like this:
40
+
### An example
41
41
42
-
```{thebe-button}
42
+
Here is what it looks like when you add the two snippets above in one example:
43
+
44
+
First the code block:
45
+
46
+
```{code-block} python
47
+
:class: thebe
48
+
print("hello world!")
43
49
```
44
50
45
-
Clicking this button will activate Thebe on the page. If you'd like to manually
46
-
add your own button (e.g. with your own extension or theme), see [](add-custom-button).
51
+
And now the Thebe button:
47
52
48
-
```{note}
49
-
By default, `sphinx-thebe` will serve the Binder environment for the
See [](configure.md) for information on choosing your own environment.
63
64
64
-
You can customize the environment that powers your interactive code sessions using
65
-
a Binder repository. This may allow for different kinds of functionality depending on
66
-
the libraries that are installed. See [](configure.md) for more information.
67
-
```
65
+
## A few examples
68
66
69
-
For example:
67
+
For example, click the button below (if you have not already clicked the button at the top of the page) and see the sections underneath to watch `sphinx-thebe` in action:
70
68
71
69
```{thebe-button} Launch examples below!
72
70
```
@@ -100,6 +98,52 @@ import matplotlib.pyplot as plt
100
98
plt.scatter(*data, c=data[0], s=200)
101
99
```
102
100
101
+
## Structure of a `thebe` cell
102
+
103
+
`sphinx-thebe` can work with two basic code cell structures:
104
+
105
+
1.**A single code cell**. In this case, there is just a single code cell that has content that should be made executable, like so:
106
+
107
+
```html
108
+
<divclass="highlight">
109
+
<pre>print("hi!")</pre>
110
+
</div>
111
+
```
112
+
2. **An input/output cell**. Jupyter tools define code cells as a combination of inputs and outputs.
113
+
For example:
114
+
115
+
```html
116
+
<divclass="cell">
117
+
<divclass="cell_input">
118
+
<pre>print("hi!")</pre>
119
+
</div>
120
+
<divclass="cell_output">
121
+
...outputs here...
122
+
</div>
123
+
</div>
124
+
```
125
+
126
+
In this case, `sphinx-thebe` will treat the `cell_output` in a special fashion, so that it is cleared when you first run its corresponding input code.
127
+
128
+
129
+
(use:selectors)=
130
+
## Selectors `sphinx-thebe` looks for by default
131
+
132
+
By default `sphinx-thebe` will look for two types of code blocks to turn into interactive cells:
133
+
134
+
- Cells that match a custom class you can add manually.
135
+
It will match:
136
+
- Whole cells: match `.thebe`
137
+
- Cell inputs: match `pre`
138
+
- Cell outputs: match `.output`
139
+
- Cells that match [MyST-NB code cells](https://myst-nb.readthedocs.io/).
140
+
It will match:
141
+
- Whole cells: match `.cell`
142
+
- Cell inputs: match `.cell_input`
143
+
- Cell outputs: match `.cell_output`
144
+
145
+
To customize the selectors that `sphinx-thebe` looks for, see [](configure:selector).
146
+
103
147
## Interactive outputs
104
148
105
149
Interactive outputs work with `sphinx-thebe`**if their web dependencies are loaded**.
0 commit comments