docs: install mdbook-tabs and update docs

.github/workflows/gh-pages.yml

@@ -30,7 +30,7 @@ jobs:
       - name: Setup mdBook
         uses: taiki-e/install-action@v2
         with:
-          tool: mdbook,lychee
+          tool: mdbook,mdbook-tabs,lychee
 
       - name: Prepare tag
         id: prepare_tag

.netlify/build.sh

@@ -89,6 +89,14 @@ if [ "${INSTALLED_MDBOOK_LINKCHECK_VERSION}" != "mdbook v${MDBOOK_LINKCHECK_VERS
     cargo install mdbook-linkcheck@${MDBOOK_LINKCHECK_VERSION} --force
 fi
 
+# Install latest mdbook-tabs. Netlify will cache the cargo bin dir, so this will
+# only build mdbook-tabs if needed.
+MDBOOK_TABS_VERSION=$(cargo search mdbook-tabs --limit 1 | head -1 | tr -s ' ' | cut -d ' ' -f 3 | tr -d '"')
+INSTALLED_MDBOOK_TABS_VERSION=$(mdbook-tabs --version || echo "none")
+if [ "${INSTALLED_MDBOOK_TABS_VERSION}" != "mdbook-tabs v${MDBOOK_TABS_VERSION}" ]; then
+    cargo install mdbook-tabs@${MDBOOK_TABS_VERSION} --force
+fi
+
 pip install nox
 nox -s build-guide
 mv target/guide/ netlify_build/main/

Contributing.md

@@ -60,7 +60,7 @@ https://doc.rust-lang.org/rustdoc/documentation-tests.html for a guide on doctes
 
 You can preview the user guide by building it locally with `mdbook`.
 
-First, install [`mdbook`][mdbook] and [`nox`][nox]. Then, run
+First, install [`mdbook`][mdbook], the [`mdbook-tabs`][mdbook-tabs] plugin and [`nox`][nox]. Then, run
 
 ```shell
 nox -s build-guide -- --open
@@ -235,5 +235,6 @@ In the meanwhile, some of our maintainers have personal GitHub sponsorship pages
 - [messense](https://github.com/sponsors/messense)
 
 [mdbook]: https://rust-lang.github.io/mdBook/cli/index.html
+[mdbook-tabs]: https://mdbook-plugins.rustforweb.org/tabs.html
 [lychee]: https://github.com/lycheeverse/lychee
 [nox]: https://github.com/theacodes/nox

guide/book.toml

@@ -6,7 +6,11 @@ author = "PyO3 Project and Contributors"
 [preprocessor.pyo3_version]
 command = "python3 guide/pyo3_version.py"
 
+[preprocessor.tabs]
+
 [output.html]
 git-repository-url = "https://github.com/PyO3/pyo3/tree/main/guide"
 edit-url-template = "https://github.com/PyO3/pyo3/edit/main/guide/{path}"
 playground.runnable = false
+additional-css = ["theme/tabs.css"]
+additional-js = ["theme/tabs.js"]

guide/src/debugging.md

@@ -66,7 +66,12 @@ For more information about how to use both `lldb` and `gdb` you can read the [gd
 
    > **Note**: When using debuggers, make sure that `python` resolves to an actual Python binary or symlink and not a shim script. Some tools like pyenv use shim scripts which can interfere with debugging.
 
-### Using rust-gdb
+### Debugger specific setup
+
+Depeding on your OS and your preferences you can use two different debuggers, `rust-gdb` or `rust-lldb`.
+
+{{#tabs }}
+{{#tab name="Using rust-gdb" }}
 
 1. Launch rust-gdb with the Python interpreter:
 
@@ -93,9 +98,8 @@ For more information about how to use both `lldb` and `gdb` you can read the [gd
    (gdb) run -m pytest tests/test_something.py::TestName
    ```
 
-### Using rust-lldb (for macOS users)
-
-On macOS, LLDB is the preferred debugger:
+{{#endtab }}
+{{#tab name="Using rust-lldb (for macOS users)" }}
 
 1. Start rust-lldb with Python:
 
@@ -122,6 +126,9 @@ On macOS, LLDB is the preferred debugger:
    (lldb) run -m pytest tests/test_something.py::TestName
    ```
 
+{{#endtab }}
+{{#endtabs }}
+
 ### Using VS Code
 
 VS Code with the Rust and Python extensions provides an integrated debugging experience:

guide/theme/tabs.css

@@ -0,0 +1,25 @@
+.mdbook-tabs {
+    display: flex;
+}
+
+.mdbook-tab {
+    background-color: var(--table-alternate-bg);
+    padding: 0.5rem 1rem;
+    cursor: pointer;
+    border: none;
+    font-size: 1.6rem;
+    line-height: 1.45em;
+}
+
+.mdbook-tab.active {
+    background-color: var(--table-header-bg);
+    font-weight: bold;
+}
+
+.mdbook-tab-content {
+    padding: 1rem 0rem;
+}
+
+.mdbook-tab-content table {
+    margin: unset;
+}

guide/theme/tabs.js

@@ -0,0 +1,75 @@
+/**
+ * Change active tab of tabs.
+ *
+ * @param {Element} container
+ * @param {string} name
+ */
+const changeTab = (container, name) => {
+    for (const child of container.children) {
+        if (!(child instanceof HTMLElement)) {
+            continue;
+        }
+
+        if (child.classList.contains('mdbook-tabs')) {
+            for (const tab of child.children) {
+                if (!(tab instanceof HTMLElement)) {
+                    continue;
+                }
+
+                if (tab.dataset.tabname === name) {
+                    tab.classList.add('active');
+                } else {
+                    tab.classList.remove('active');
+                }
+            }
+        } else if (child.classList.contains('mdbook-tab-content')) {
+            if (child.dataset.tabname === name) {
+                child.classList.remove('hidden');
+            } else {
+                child.classList.add('hidden');
+            }
+        }
+    }
+};
+
+document.addEventListener('DOMContentLoaded', () => {
+    const tabs = document.querySelectorAll('.mdbook-tab');
+    for (const tab of tabs) {
+        tab.addEventListener('click', () => {
+            if (!(tab instanceof HTMLElement)) {
+                return;
+            }
+
+            if (!tab.parentElement || !tab.parentElement.parentElement) {
+                return;
+            }
+
+            const container = tab.parentElement.parentElement;
+            const name = tab.dataset.tabname;
+            const global = container.dataset.tabglobal;
+
+            changeTab(container, name);
+
+            if (global) {
+                localStorage.setItem(`mdbook-tabs-${global}`, name);
+
+                const globalContainers = document.querySelectorAll(
+                    `.mdbook-tabs-container[data-tabglobal="${global}"]`
+                );
+                for (const globalContainer of globalContainers) {
+                    changeTab(globalContainer, name);
+                }
+            }
+        });
+    }
+
+    const containers = document.querySelectorAll('.mdbook-tabs-container[data-tabglobal]');
+    for (const container of containers) {
+        const global = container.dataset.tabglobal;
+
+        const name = localStorage.getItem(`mdbook-tabs-${global}`);
+        if (name && document.querySelector(`.mdbook-tab[data-tabname=${name}]`)) {
+            changeTab(container, name);
+        }
+    }
+});