Skip to content
Snippets Groups Projects
Unverified Commit edae9e5e authored by Chris Holdgraf's avatar Chris Holdgraf Committed by GitHub
Browse files

:books: DOCS: sphinx_inline_tabs example (#1099)

parent 8a791f82
No related branches found
No related tags found
No related merge requests found
......@@ -93,5 +93,5 @@ sphinx:
extra_extensions:
- sphinx_click.ext
- sphinx_tabs.tabs
- sphinx_inline_tabs
- sphinxext.rediraffe
......@@ -35,68 +35,103 @@ Make sure that you have your extension installed on your machine, or Sphinx won'
how to build the extensions.
:::
### An example: `sphinx-tabs`
### An example: `sphinx-inline-tabs`
For example, let's say you'd like to include **tabbed content** in your book.
There is [a Sphinx extension for that](https://github.com/djungelorm/sphinx-tabs).
To enable it, we'll do the following:
By default, Jupyter Book ships with [tabs via `sphinx-panels`](content:tabs).
There are other packages for tabs in the Sphinx ecosystem with different functionality.
One-such package is [`sphinx-inline-tabs`](https://sphinx-inline-tabs.readthedocs.io/en/latest/), which allows for _syncronized tabs_ in case you'd like your tabs to shift across the page at the same time.
* **Install `sphinx-tabs`**. Here's the command to do so:
`sphinx-inline-tabs` is not included with Jupyter Book by default, but we can activate it with Jupyter Book like so:
* **Install `sphinx-inline-tabs`**. Here's the command to do so:
```bash
pip install sphinx-tabs
pip install sphinx-inline-tabs
```
* **Add `sphinx-tabs` content to your book**. Here's an example with MyST Markdown:
* **Add `sphinx-inline-tabs` content to your book**. Here's an example with MyST Markdown:
`````md
````{tabs}
```{tab} Line one
Beautiful is better than ugly. ✨
First two tabs showing off defining a function.
````{tab} Python
```python
def main():
return
```
```{tab} Line two
````
````{tab} C++
```c++
int main(const int argc, const char **argv) {
return 0;
}
```
````
Explicit is better than implicit. ❗
Second two tabs showing off printing.
````{tab} Python
```python
print("Hello World!")
```
```{tab} Line three
````
Simple is better than complex. 😵
````{tab} C++
```c++
#include <iostream>
int main() {
std::cout << "Hello World!" << std::endl;
}
```
````
`````
* **Activate `sphinx-tabs` in `_config.yml`**. [The `sphinx-tabs` documentation](https://github.com/djungelorm/sphinx-tabs#installation)
says we activate it in Sphinx by adding `extensions = ["sphinx_tabs.tabs"]`, so we'll
add it to our Jupyter Book like so:
* **Activate `sphinx-inline-tabs` in `_config.yml`**.
[The `sphinx-inline-tabs` documentation](https://sphinx-inline-tabs.readthedocs.io/en/latest/) says we activate it in Sphinx by adding `extensions = ["sphinx_inline_tabs"]`, so we'll add it to our Jupyter Book like so:
```yaml
sphinx:
extra_extensions:
- sphinx_tabs.tabs
- sphinx_inline_tabs
```
Now, Jupyter Book will know how to interpret the `{tabs}` directive
(and any other directives that `sphinx-tabs` supports).
Now, Jupyter Book will know how to interpret the `{tab}` directive
(and any other directives that `sphinx-inline-tabs` supports).
For example, here is a rendered version of the tab code pasted above:
The [Zen of Python](https://www.python.org/dev/peps/pep-0020/), in 3 tabs.
First two tabs showing off defining a function.
````{tabs}
```{tab} Line one
````{tab} Python
```python
def main():
return
```
````
````{tab} C++
```c++
int main(const int argc, const char **argv) {
return 0;
}
```
````
Beautiful is better than ugly. ✨
Second two tabs showing off printing.
````{tab} Python
```python
print("Hello World!")
```
```{tab} Line two
````
Explicit is better than implicit. ❗
```
```{tab} Line three
````{tab} C++
```c++
#include <iostream>
Simple is better than complex. 😵
int main() {
std::cout << "Hello World!" << std::endl;
}
```
````
......
......@@ -563,6 +563,7 @@ To reference terms in your glossary, use the `{term}` role. For example,
`` {term}`Term one` `` becomes {term}`Term one` and `` {term}`A second term` ``
becomes {term}`A second term`.
(content:tabs)=
## Tabbed content
You can also use [`sphinx-panels`](sphinx-panels:panels/usage) to produce [**tabbed content**](sphinx-panels:components-tabbed).
......
......@@ -10,6 +10,6 @@ plotly
bokeh
altair
sphinx-click
sphinx_tabs
sphinx_inline_tabs
jupytext~=1.6.0
sphinxext-rediraffe~=0.2.3
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment