From e86b1c48d591d50ca5befb24f9dce013e092b044 Mon Sep 17 00:00:00 2001 From: Enrico Bravi <49145850+cinghioGithub@users.noreply.github.com> Date: Fri, 26 Jul 2024 13:56:56 +0200 Subject: [PATCH 01/10] docs: contribute: update Linux kernel contribution guideline Linux kernel contribution does not happen on Github, but on mailing list. Update this information in the Linux kernel contribution guideline. Signed-off-by: Enrico Bravi --- .../asciidoc/computers/linux_kernel/contribute.adoc | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/documentation/asciidoc/computers/linux_kernel/contribute.adoc b/documentation/asciidoc/computers/linux_kernel/contribute.adoc index 07a633587..6f430fe18 100644 --- a/documentation/asciidoc/computers/linux_kernel/contribute.adoc +++ b/documentation/asciidoc/computers/linux_kernel/contribute.adoc @@ -18,6 +18,7 @@ Then, submit a pull request containing your changes to the https://github.com/ra === Contribute to the Linux kernel -First, fork the https://github.com/torvalds/linux[Linux kernel repository] and clone it to your development device. You can then make your changes, test them, and commit them into your fork. +First, clone the https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git[Linux kernel tree] to your development device. You can then make your changes, test them, and commit them into your fork. -Then, submit a pull request containing your changes to the https://github.com/torvalds/linux[Linux kernel repository]. Linux kernel contributors will review your contribution and suggest improvements. Once approved, they'll merge in your changes. Eventually, they'll make their way into a long-term release of the Linux kernel. Once we've tested that long-term release for compatibility with the Raspberry Pi kernel, your changes will make their way into a stable release of the Raspberry Pi kernel. +Once your change is ready you can submit it to the Linux kernel community. Linux kernel development happens on mailing lists, rather than on GitHub, so that your change can become part of Linux, please email it to the community as a patch. Please follow the https://www.kernel.org/doc/html/latest/process/submitting-patches.html[Submitting patches: the essential guide to getting your code into the kernel] in the Linux kernel documentation. +Linux kernel contributors will review your contribution and suggest improvements. Once approved, they'll merge in your changes. Eventually, they'll make their way into a long-term release of the Linux kernel. Once we've tested that long-term release for compatibility with the Raspberry Pi kernel, your changes will make their way into a stable release of the Raspberry Pi kernel. From 8e48cc157df1ae6bc09a85af23c239ef2a31b8ec Mon Sep 17 00:00:00 2001 From: Enrico Bravi <49145850+cinghioGithub@users.noreply.github.com> Date: Mon, 29 Jul 2024 15:23:03 +0200 Subject: [PATCH 02/10] docs: contribute: addressed PR review comments - Fixed style problems - Add Linux kernel coding style reference Signed-off-by: Enrico Bravi --- documentation/asciidoc/computers/linux_kernel/contribute.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/documentation/asciidoc/computers/linux_kernel/contribute.adoc b/documentation/asciidoc/computers/linux_kernel/contribute.adoc index 6f430fe18..74d03d865 100644 --- a/documentation/asciidoc/computers/linux_kernel/contribute.adoc +++ b/documentation/asciidoc/computers/linux_kernel/contribute.adoc @@ -18,7 +18,7 @@ Then, submit a pull request containing your changes to the https://github.com/ra === Contribute to the Linux kernel -First, clone the https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git[Linux kernel tree] to your development device. You can then make your changes, test them, and commit them into your fork. +First, clone the https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git[Linux kernel tree] to your development device. You can then make your changes, test them, and commit them into your local tree. -Once your change is ready you can submit it to the Linux kernel community. Linux kernel development happens on mailing lists, rather than on GitHub, so that your change can become part of Linux, please email it to the community as a patch. Please follow the https://www.kernel.org/doc/html/latest/process/submitting-patches.html[Submitting patches: the essential guide to getting your code into the kernel] in the Linux kernel documentation. +Once your change is ready you can submit it to the Linux kernel community. Linux kernel development happens on mailing lists, rather than on GitHub. In order for your change to become part of Linux, please email it to the community as a patch. Please follow https://www.kernel.org/doc/html/latest/process/submitting-patches.html[Submitting patches: the essential guide to getting your code into the kernel] and https://www.kernel.org/doc/html/latest/process/coding-style.html[Linux kernel coding style] in the Linux kernel documentation. Linux kernel contributors will review your contribution and suggest improvements. Once approved, they'll merge in your changes. Eventually, they'll make their way into a long-term release of the Linux kernel. Once we've tested that long-term release for compatibility with the Raspberry Pi kernel, your changes will make their way into a stable release of the Raspberry Pi kernel. From c635e717f3d50eef83521d4cc12356a124700c7d Mon Sep 17 00:00:00 2001 From: Paul Mucur Date: Wed, 21 Aug 2024 15:22:09 +0100 Subject: [PATCH 03/10] Update doxygentoasciidoc to latest version The latest version replaces the "-f" argument with a single positional argument so update our Makefile accordingly. --- Makefile | 6 +++--- lib/doxygentoasciidoc | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/Makefile b/Makefile index 7e0bc6854..e3a8c396e 100644 --- a/Makefile +++ b/Makefile @@ -83,9 +83,9 @@ clean_doxygen_xml: $(ASCIIDOC_DOXYGEN_DIR)/picosdk_index.json $(ASCIIDOC_DOXYGEN_DIR)/index_doxygen.adoc: $(ASCIIDOC_DOXYGEN_DIR) $(DOXYGEN_XML_DIR)/index.xml $(DOXYGEN_TO_ASCIIDOC_DIR)/__main__.py $(DOXYGEN_TO_ASCIIDOC_DIR)/cli.py $(DOXYGEN_TO_ASCIIDOC_DIR)/nodes.py $(DOXYGEN_TO_ASCIIDOC_DIR)/helpers.py | $(BUILD_DIR) $(DOXYGEN_TO_ASCIIDOC_DIR)/requirements.txt $(MAKE) clean_ninja pip3 install -r $(DOXYGEN_TO_ASCIIDOC_DIR)/requirements.txt - PYTHONPATH=$(DOXYGEN_TO_ASCIIDOC_DIR)/.. python3 -m doxygentoasciidoc -f $(DOXYGEN_XML_DIR)/index.xml -o $(ASCIIDOC_DOXYGEN_DIR)/all_groups.adoc - PYTHONPATH=$(DOXYGEN_TO_ASCIIDOC_DIR)/.. python3 -m doxygentoasciidoc -f $(DOXYGEN_XML_DIR)/indexpage.xml -c -o $(ASCIIDOC_DOXYGEN_DIR)/index_doxygen.adoc - PYTHONPATH=$(DOXYGEN_TO_ASCIIDOC_DIR)/.. python3 -m doxygentoasciidoc -f $(DOXYGEN_XML_DIR)/examples_page.xml -c -o $(ASCIIDOC_DOXYGEN_DIR)/examples_page.adoc + PYTHONPATH=$(DOXYGEN_TO_ASCIIDOC_DIR)/.. python3 -m doxygentoasciidoc -o $(ASCIIDOC_DOXYGEN_DIR)/all_groups.adoc $(DOXYGEN_XML_DIR)/index.xml + PYTHONPATH=$(DOXYGEN_TO_ASCIIDOC_DIR)/.. python3 -m doxygentoasciidoc -c -o $(ASCIIDOC_DOXYGEN_DIR)/index_doxygen.adoc $(DOXYGEN_XML_DIR)/indexpage.xml + PYTHONPATH=$(DOXYGEN_TO_ASCIIDOC_DIR)/.. python3 -m doxygentoasciidoc -c -o $(ASCIIDOC_DOXYGEN_DIR)/examples_page.adoc $(DOXYGEN_XML_DIR)/examples_page.xml python3 $(SCRIPTS_DIR)/postprocess_doxygen_adoc.py $(ASCIIDOC_DOXYGEN_DIR) -cp $(DOXYGEN_XML_DIR)/*.png $(ASCIIDOC_DOXYGEN_DIR) 2>/dev/null || true diff --git a/lib/doxygentoasciidoc b/lib/doxygentoasciidoc index 278bc0874..09e14b6d2 160000 --- a/lib/doxygentoasciidoc +++ b/lib/doxygentoasciidoc @@ -1 +1 @@ -Subproject commit 278bc087489951a22c776ee611965d600db4547f +Subproject commit 09e14b6d2fc7fd016e4556a8e10027033fb7b517 From 20d378203afd387bd634e73b498b0a1ad399102d Mon Sep 17 00:00:00 2001 From: ykla Date: Fri, 23 Aug 2024 09:06:43 +0800 Subject: [PATCH 04/10] Make note conform to AsciiDoc syntax --- documentation/asciidoc/computers/legacy_config_txt/video.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/asciidoc/computers/legacy_config_txt/video.adoc b/documentation/asciidoc/computers/legacy_config_txt/video.adoc index 68a0fc73a..ba0c7bcf6 100644 --- a/documentation/asciidoc/computers/legacy_config_txt/video.adoc +++ b/documentation/asciidoc/computers/legacy_config_txt/video.adoc @@ -1678,7 +1678,7 @@ Increase this value if the text flows off the bottom edge of the screen; decreas Set `overscan_scale` to `1` to force any non-framebuffer layers to conform to the overscan settings. The default value is `0`. -*NOTE:* this feature is generally not recommended: it can reduce image quality because all layers on the display will be scaled by the GPU. Disabling overscan on the display itself is the recommended option to avoid images being scaled twice (by the GPU and the display). +NOTE: this feature is generally not recommended: it can reduce image quality because all layers on the display will be scaled by the GPU. Disabling overscan on the display itself is the recommended option to avoid images being scaled twice (by the GPU and the display). ==== `framebuffer_width` From 86a2554188e269c537262d1a3087b1dfce328a1d Mon Sep 17 00:00:00 2001 From: gllxflr <149011830+gllxflr@users.noreply.github.com> Date: Sat, 31 Aug 2024 21:15:26 +0100 Subject: [PATCH 05/10] Fix small issue with Connect Remote Shell docs It mistakenly said "to re-enable screen sharing" instead of correctly mentioning remote shell access --- documentation/asciidoc/services/connect/use.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/asciidoc/services/connect/use.adoc b/documentation/asciidoc/services/connect/use.adoc index aee1731b5..207afe6f3 100644 --- a/documentation/asciidoc/services/connect/use.adoc +++ b/documentation/asciidoc/services/connect/use.adoc @@ -184,7 +184,7 @@ In the Connect dashboard, the **Remote shell** badge and the **Remote shell** op image::images/remote-shell-disabled.png[width="80%"] -To re-enable screen sharing, do one of the following: +To re-enable remote shell access, do one of the following: * click the Connect system tray icon and select **Allow remote shell** * run the following command: From 410705f3f21179b58dedcd890a3008f1c471873c Mon Sep 17 00:00:00 2001 From: Steven Guido Date: Sun, 1 Sep 2024 09:43:33 +0200 Subject: [PATCH 06/10] remove old config option --- .../asciidoc/computers/configuration/raspi-config.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/documentation/asciidoc/computers/configuration/raspi-config.adoc b/documentation/asciidoc/computers/configuration/raspi-config.adoc index 4d1f02c22..2fd95ad36 100644 --- a/documentation/asciidoc/computers/configuration/raspi-config.adoc +++ b/documentation/asciidoc/computers/configuration/raspi-config.adoc @@ -551,7 +551,7 @@ Enable or disable the serial connection hardware. [source,console] ---- -$ sudo raspi-config nonint do_serial_hw <0/1/2> +$ sudo raspi-config nonint do_serial_hw <0/1> ---- * `0`: enable serial port @@ -564,7 +564,7 @@ Enable or disable shell and kernel messages on the serial connection. [source,console] ---- -$ sudo raspi-config nonint do_serial_cons <0/1/2> +$ sudo raspi-config nonint do_serial_cons <0/1> ---- * `0`: enable console over serial port From fc59f89fd59105165979644d43d96c102aa533e7 Mon Sep 17 00:00:00 2001 From: ykla Date: Wed, 4 Sep 2024 19:17:26 +0800 Subject: [PATCH 07/10] Fixed an error in the NFS server setup documentation. --- documentation/asciidoc/computers/remote-access/nfs.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/asciidoc/computers/remote-access/nfs.adoc b/documentation/asciidoc/computers/remote-access/nfs.adoc index 2e5a5f6bc..5db9c843c 100644 --- a/documentation/asciidoc/computers/remote-access/nfs.adoc +++ b/documentation/asciidoc/computers/remote-access/nfs.adoc @@ -36,7 +36,7 @@ Grant `/export` and `/export/users` read, write, and execute permissions (`777`) [source,console] ---- -$ chmod -R 777 777 /export +$ chmod -R 777 /export ---- Next, mount the real `users` directory with: From 688331024a9fb363f0f7f5e356ffc0c93a23d018 Mon Sep 17 00:00:00 2001 From: ykla Date: Wed, 4 Sep 2024 20:48:06 +0800 Subject: [PATCH 08/10] Fix list format --- documentation/asciidoc/computers/camera/rpicam_apps_writing.adoc | 1 + 1 file changed, 1 insertion(+) diff --git a/documentation/asciidoc/computers/camera/rpicam_apps_writing.adoc b/documentation/asciidoc/computers/camera/rpicam_apps_writing.adoc index 86287613d..fd5a9217b 100644 --- a/documentation/asciidoc/computers/camera/rpicam_apps_writing.adoc +++ b/documentation/asciidoc/computers/camera/rpicam_apps_writing.adoc @@ -3,6 +3,7 @@ `rpicam-apps` does not provide all of the camera-related features that anyone could ever need. Instead, these applications are small and flexible. Users who require different behaviour can implement it themselves. All of the `rpicam-apps` use an event loop that receives messages when a new set of frames arrives from the camera system. This set of frames is called a `CompletedRequest`. The `CompletedRequest` contains: + * all images derived from that single camera frame: often a low-resolution image and a full-size output * metadata from the camera and post-processing systems From 874af1311e09eedab1af9343e347f1349f825054 Mon Sep 17 00:00:00 2001 From: Andrew Scheller Date: Thu, 5 Sep 2024 11:27:20 +0100 Subject: [PATCH 09/10] Fix glaring typo --- .../computers/configuration/kernel-command-line-config.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/asciidoc/computers/configuration/kernel-command-line-config.adoc b/documentation/asciidoc/computers/configuration/kernel-command-line-config.adoc index c97657f3e..27fbc1c26 100644 --- a/documentation/asciidoc/computers/configuration/kernel-command-line-config.adoc +++ b/documentation/asciidoc/computers/configuration/kernel-command-line-config.adoc @@ -46,7 +46,7 @@ If no `video` entry is present in `cmdline.txt`, Raspberry Pi OS uses the https: video=HDMI-A-1:1920x1080M@60 ---- -In addition, it is possible to add rotation and reflect parameters as documented in the standard https://github.com/raspberrypi/linux/blob/rpi-6.1.y/Documentation/fb/modedb.rst[Linux framebuffer documentation]. The following example defines a display named `HDMI-A-` at a resolution of 1080p, a refresh rate of 60Hz, 90 degrees of rotation, and a reflection over the X axis: +In addition, it is possible to add rotation and reflect parameters as documented in the standard https://github.com/raspberrypi/linux/blob/rpi-6.1.y/Documentation/fb/modedb.rst[Linux framebuffer documentation]. The following example defines a display named `HDMI-A-1` at a resolution of 1080p, a refresh rate of 60Hz, 90 degrees of rotation, and a reflection over the X axis: [source,bash] ---- From 6f66e07032ebda816e1e0551498f55474b060b7f Mon Sep 17 00:00:00 2001 From: Nate Contino Date: Fri, 6 Sep 2024 13:21:09 -0400 Subject: [PATCH 10/10] Add tabs to the documentation --- .gitignore | 1 + Gemfile | 4 +- Gemfile.lock | 4 + _config.yml | 1 + .../asciidoc/computers/remote-access/ssh.adoc | 21 +-- jekyll-assets/_includes/head.html | 1 + jekyll-assets/_includes/scripts.html | 3 + jekyll-assets/css/asciidoctor-tabs.css | 116 ++++++++++++++++ jekyll-assets/css/tabs.css | 2 +- jekyll-assets/scripts/asciidoctor-tabs.js | 127 ++++++++++++++++++ 10 files changed, 269 insertions(+), 11 deletions(-) create mode 100644 jekyll-assets/css/asciidoctor-tabs.css create mode 100644 jekyll-assets/scripts/asciidoctor-tabs.js diff --git a/.gitignore b/.gitignore index 2984493b5..1d7ee958d 100644 --- a/.gitignore +++ b/.gitignore @@ -4,3 +4,4 @@ build build-pico-sdk-docs documentation/html documentation/asciidoc/pico-sdk +.venv diff --git a/Gemfile b/Gemfile index a54d14c20..d342d0b9a 100644 --- a/Gemfile +++ b/Gemfile @@ -21,6 +21,8 @@ gem "minima", "~> 2.0" group :jekyll_plugins do gem "jekyll-feed", "~> 0.17" gem 'jekyll-asciidoc' + gem 'asciidoctor' + gem 'asciidoctor-tabs', ">= 1.0.0.beta.6" end # Windows does not include zoneinfo files, so bundle the tzinfo-data gem @@ -37,4 +39,4 @@ gem "nokogiri", "~> 1.16" # So we can add custom element templates gem 'slim', '~> 5.2.1' -gem 'thread_safe', '~> 0.3.5' \ No newline at end of file +gem 'thread_safe', '~> 0.3.5' diff --git a/Gemfile.lock b/Gemfile.lock index a8d10ab26..5808c168c 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -4,6 +4,8 @@ GEM addressable (2.8.6) public_suffix (>= 2.0.2, < 6.0) asciidoctor (2.0.20) + asciidoctor-tabs (1.0.0.beta.6) + asciidoctor (>= 2.0.0, < 3.0.0) colorator (1.1.0) concurrent-ruby (1.2.3) em-websocket (0.5.3) @@ -94,6 +96,8 @@ PLATFORMS ruby DEPENDENCIES + asciidoctor + asciidoctor-tabs (>= 1.0.0.beta.6) jekyll (~> 4.3.3) jekyll-asciidoc jekyll-feed (~> 0.17) diff --git a/_config.yml b/_config.yml index acfa472d3..66a8c67ba 100644 --- a/_config.yml +++ b/_config.yml @@ -25,6 +25,7 @@ githubbranch_edit: develop # Build settings theme: minima plugins: + - asciidoctor-tabs - jekyll-asciidoc - jekyll-feed diff --git a/documentation/asciidoc/computers/remote-access/ssh.adoc b/documentation/asciidoc/computers/remote-access/ssh.adoc index 0d3e38513..acdec020d 100644 --- a/documentation/asciidoc/computers/remote-access/ssh.adoc +++ b/documentation/asciidoc/computers/remote-access/ssh.adoc @@ -7,24 +7,26 @@ You can access the terminal of a Raspberry Pi remotely from another computer on By default, Raspberry Pi OS disables the SSH server. Enable SSH in one of the following ways: -==== On the desktop - +[tabs] +====== +On the desktop:: ++ . From the *Preferences* menu, launch *Raspberry Pi Configuration*. . Navigate to the *Interfaces* tab. . Select *Enabled* next to *SSH*. . Click *OK*. -==== While flashing a fresh OS image - +While flashing a fresh OS image:: ++ To configure SSH on a completely new installation of Raspberry Pi OS: - ++ . Follow the instructions in the xref:../computers/getting-started.adoc#raspberry-pi-imager[Install with Imager] guide. . During the **OS Customisation** step, navigate to the **Services** tab. . Tick the checkbox to **Enable SSH**. . Select **password authentication** to log in using the same username and password you use while physically using your Raspberry Pi. Select **Allow public-key authentication only** to xref:remote-access.adoc#configure-ssh-without-a-password[configure an SSH key] for passwordless login. -==== From the terminal - +From the terminal:: ++ . Enter `sudo raspi-config` in a terminal window. . Select `Interfacing Options`. . Navigate to and select `SSH`. @@ -32,8 +34,8 @@ To configure SSH on a completely new installation of Raspberry Pi OS: . Select `Ok`. . Choose `Finish`. -==== Manually - +Manually:: ++ . Create an empty file named `ssh` in the boot partition: + [source,console] @@ -46,6 +48,7 @@ $ sudo touch /boot/firmware/ssh ---- $ sudo reboot ---- +====== === Connect to an SSH server diff --git a/jekyll-assets/_includes/head.html b/jekyll-assets/_includes/head.html index 369ae8646..4780553b3 100644 --- a/jekyll-assets/_includes/head.html +++ b/jekyll-assets/_includes/head.html @@ -18,6 +18,7 @@ + + + + diff --git a/jekyll-assets/css/asciidoctor-tabs.css b/jekyll-assets/css/asciidoctor-tabs.css new file mode 100644 index 000000000..1afbd9185 --- /dev/null +++ b/jekyll-assets/css/asciidoctor-tabs.css @@ -0,0 +1,116 @@ + +/*! Asciidoctor Tabs | Copyright (c) 2018-present Dan Allen | MIT License */ +.tabs { + margin-bottom: 1.25em; +} + +.tablist > ul { + display: flex; + flex-wrap: nowrap; + overflow-x: scroll; + overflow-y: hidden; + list-style: none; + margin: 0; + padding: 0; +} + +.tablist > ul li { + align-items: center; + background-color: #eee; + cursor: pointer; + display: flex; + font-weight: bold; + line-height: 1.5; + padding: 0.25em 1em; + position: relative; +} + +.tablist > ul li p { + margin-bottom: 0px !important; +} + +.tablist > ul li:focus-visible { + outline: none; +} + +.tablist.ulist, +.tablist.ulist > ul li { + margin: 0; +} + +.tablist.ulist > ul li + li { + margin-left: 0.25em; +} + +.tabs .tablist li::after { + content: ""; + display: block; + height: 1px; + position: absolute; + bottom: -1px; + left: 0; + right: 0; +} + +.tabs.is-loading .tablist li:not(:first-child), +.tabs:not(.is-loading) .tablist li:not(.is-selected) { + background-color: initial; + border-left: 1px solid #eee; + border-right: 1px solid #eee; + border-top: 1px solid #eee; +} + +.tabs.is-loading .tablist li:first-child::after, +.tabs:not(.is-loading) .tablist li.is-selected::after { + background-color: #eee; + border-top: 2px solid var(--red); +} + +/* +.tabs:not(.is-loading) .tablist li, +.tabs:not(.is-loading) .tablist li::after { + transition: background-color 200ms ease-in-out; +} +*/ + +.tablist > ul p { + line-height: inherit; + margin: 0; +} + +.tabpanel { + background-color: #eee; + padding: 1.25em; +} + +.tablist > ul li { + border-bottom: 0; +} + +.tabs.is-loading .tabpanel + .tabpanel, +.tabs:not(.is-loading) .tabpanel.is-hidden { + display: none; +} + +.tabpanel > :first-child { + margin-top: 0; +} + +/* #content is a signature of the Asciidoctor standalone HTML output */ +#content .tabpanel > :last-child, +#content .tabpanel > :last-child > :last-child, +#content .tabpanel > :last-child > :last-child > li:last-child > :last-child { + margin-bottom: 0; +} + +.tablecontainer { + overflow-x: auto; +} + +#content .tablecontainer { + margin-bottom: 1.25em; +} + +#content .tablecontainer > table.tableblock { + margin-bottom: 0; +} diff --git a/jekyll-assets/css/tabs.css b/jekyll-assets/css/tabs.css index 04d927ed0..b1880c02a 100644 --- a/jekyll-assets/css/tabs.css +++ b/jekyll-assets/css/tabs.css @@ -79,4 +79,4 @@ p#release + #container { display: block; width: 100%; } -} +} \ No newline at end of file diff --git a/jekyll-assets/scripts/asciidoctor-tabs.js b/jekyll-assets/scripts/asciidoctor-tabs.js new file mode 100644 index 000000000..f8966c024 --- /dev/null +++ b/jekyll-assets/scripts/asciidoctor-tabs.js @@ -0,0 +1,127 @@ +;(function () { /*! Asciidoctor Tabs | Copyright (c) 2018-present Dan Allen | MIT License */ + 'use strict' + + var config = (document.currentScript || {}).dataset || {} + var forEach = Array.prototype.forEach + + init(document.querySelectorAll('.tabs')) + + function init (tabsBlocks) { + if (!tabsBlocks.length) return + forEach.call(tabsBlocks, function (tabs) { + var syncIds = tabs.classList.contains('is-sync') ? {} : undefined + var tablist = tabs.querySelector('.tablist ul') + tablist.setAttribute('role', 'tablist') + var start + forEach.call(tablist.querySelectorAll('li'), function (tab, idx) { + tab.tabIndex = -1 + tab.setAttribute('role', tab.classList.add('tab') || 'tab') + var id, anchor, syncId + if (!(id = tab.id) && (anchor = tab.querySelector('a[id]'))) { + id = tab.id = anchor.parentNode.removeChild(anchor).id + } + var panel = id && tabs.querySelector('.tabpanel[aria-labelledby~="' + id + '"]') + if (!panel) return idx ? undefined : toggleSelected(tab, true) // invalid state + syncIds && (((syncId = tab.textContent.trim()) in syncIds) ? (syncId = undefined) : true) && + (syncIds[(tab.dataset.syncId = syncId)] = tab) + idx || (syncIds && (start = { tab: tab, panel: panel })) ? toggleHidden(panel, true) : toggleSelected(tab, true) + tab.setAttribute('aria-controls', panel.id) + panel.setAttribute('role', 'tabpanel') + var onClick = syncId === undefined ? activateTab : activateTabSync + tab.addEventListener('click', onClick.bind({ tabs: tabs, tab: tab, panel: panel })) + }) + if (!tabs.closest('.tabpanel')) { + forEach.call(tabs.querySelectorAll('.tabpanel table.tableblock'), function (table) { + var container = Object.assign(document.createElement('div'), { className: 'tablecontainer' }) + table.parentNode.insertBefore(container, table).appendChild(table) + }) + } + if (start) { + var syncGroupId + for (var i = 0, lst = tabs.classList, len = lst.length, className; i !== len; i++) { + if (!(className = lst.item(i)).startsWith('data-sync-group-id=')) continue + tabs.dataset.syncGroupId = syncGroupId = lst.remove(className) || className.slice(19).replace(/\u00a0/g, ' ') + break + } + if (syncGroupId === undefined) tabs.dataset.syncGroupId = syncGroupId = Object.keys(syncIds).sort().join('|') + var preferredSyncId = 'syncStorageKey' in config && + window[(config.syncStorageScope || 'local') + 'Storage'].getItem(config.syncStorageKey + '-' + syncGroupId) + var tab = preferredSyncId && syncIds[preferredSyncId] + tab && Object.assign(start, { tab: tab, panel: document.getElementById(tab.getAttribute('aria-controls')) }) + toggleSelected(start.tab, true) || toggleHidden(start.panel, false) + } + }) + onHashChange() + toggleClassOnEach(tabsBlocks, 'is-loading', 'remove') + window.setTimeout(toggleClassOnEach.bind(null, tabsBlocks, 'is-loaded', 'add'), 0) + window.addEventListener('hashchange', onHashChange) + } + + function activateTab (e) { + var tab = this.tab + var tabs = this.tabs || (this.tabs = tab.closest('.tabs')) + var panel = this.panel || (this.panel = document.getElementById(tab.getAttribute('aria-controls'))) + querySelectorWithSiblings(tabs, '.tablist .tab', 'tab').forEach(function (el) { + toggleSelected(el, el === tab) + }) + querySelectorWithSiblings(tabs, '.tabpanel', 'tabpanel').forEach(function (el) { + toggleHidden(el, el !== panel) + }) + if (!this.isSync && 'syncStorageKey' in config && 'syncGroupId' in tabs.dataset) { + var storageKey = config.syncStorageKey + '-' + tabs.dataset.syncGroupId + window[(config.syncStorageScope || 'local') + 'Storage'].setItem(storageKey, tab.dataset.syncId) + } + if (!e) return + var loc = window.location + var hashIdx = loc.hash ? loc.href.indexOf('#') : -1 + if (~hashIdx) window.history.replaceState(null, '', loc.href.slice(0, hashIdx)) + e.preventDefault() + } + + function activateTabSync (e) { + activateTab.call(this, e) + var thisTabs = this.tabs + var thisTab = this.tab + var initialY = thisTabs.getBoundingClientRect().y + forEach.call(document.querySelectorAll('.tabs'), function (tabs) { + if (tabs === thisTabs || tabs.dataset.syncGroupId !== thisTabs.dataset.syncGroupId) return + querySelectorWithSiblings(tabs, '.tablist .tab', 'tab').forEach(function (tab) { + if (tab.dataset.syncId === thisTab.dataset.syncId) activateTab.call({ tabs: tabs, tab: tab, isSync: true }) + }) + }) + var shiftedBy = thisTabs.getBoundingClientRect().y - initialY + if (shiftedBy && (shiftedBy = Math.round(shiftedBy))) window.scrollBy({ top: shiftedBy, behavior: 'instant' }) + } + + function querySelectorWithSiblings (scope, selector, siblingClass) { + var el = scope.querySelector(selector) + if (!el) return [] + var result = [el] + while ((el = el.nextElementSibling) && el.classList.contains(siblingClass)) result.push(el) + return result + } + + function toggleClassOnEach (elements, className, method) { + forEach.call(elements, function (el) { + el.classList[method](className) + }) + } + + function toggleHidden (el, state) { + el.classList[(el.hidden = state) ? 'add' : 'remove']('is-hidden') + } + + function toggleSelected (el, state) { + el.setAttribute('aria-selected', '' + state) + el.classList[state ? 'add' : 'remove']('is-selected') + el.tabIndex = state ? 0 : -1 + } + + function onHashChange () { + var id = window.location.hash.slice(1) + if (!id) return + var tab = document.getElementById(~id.indexOf('%') ? decodeURIComponent(id) : id) + if (!(tab && tab.classList.contains('tab'))) return + 'syncId' in tab.dataset ? activateTabSync.call({ tab: tab }) : activateTab.call({ tab: tab }) + } +})()