Merge pull request #3839 from raspberrypi/develop

nathan-contino · web-flow · commit 1b7709fea907 · 2024-09-06T18:36:59.000+01:00
Roll out latest develop changes to production
diff --git 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
@@ -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'
+gem 'thread_safe', '~> 0.3.5'
diff --git 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/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/_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/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
 
diff --git 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]
 ----
diff --git 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
diff --git 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`
 
diff --git 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 local tree.
 
-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. 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.
diff --git 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:
diff --git a/documentation/asciidoc/computers/remote-access/ssh.adoc b/documentation/asciidoc/computers/remote-access/ssh.adoc
@@ -7,33 +7,35 @@ 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`.
 . Choose `Yes`.
 . 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/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:
diff --git a/jekyll-assets/_includes/head.html b/jekyll-assets/_includes/head.html
@@ -18,6 +18,7 @@
 <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@docsearch/css@3"/>
 <link rel="stylesheet" href="{{ site.baseurl }}/css/style.css?ver={{ site.time | date: '%s' }}">
 <link rel="stylesheet" href="{{ site.baseurl }}/css/tabs.css?ver={{ site.time | date: '%s' }}">
+<link rel="stylesheet" href="{{ site.baseurl }}/css/asciidoctor-tabs.css?ver={{ site.time | date: '%s' }}">
 <link rel="stylesheet" href="{{ site.baseurl }}/css/syntax-highlighting.css?ver={{ site.time | date: '%s' }}">
 <script async src="https://www.googletagmanager.com/gtag/js?id=UA-180927933-8"></script>
 <script>
diff --git a/jekyll-assets/_includes/scripts.html b/jekyll-assets/_includes/scripts.html
@@ -1,6 +1,9 @@
 <!-- Script for the TOC toggle -->
 <script src="{{ site.baseurl }}/scripts/nav.js?ver={{ site.time | date: '%s' }}" type="text/javascript"></script>
 
+<!-- Asciidoctor tabs -->
+<script src="{{ site.baseurl }}/scripts/asciidoctor-tabs.js?ver={{ site.time | date: '%s' }}" type="text/javascript"></script>
+
 <!-- TOCify scripts -->
 <script src="{{ site.baseurl }}/scripts/jquery-1.12.4.min.js"></script>
 <script src="{{ site.baseurl }}/scripts/jquery-ui-1.13.0.custom.min.js"></script>
diff --git a/jekyll-assets/css/asciidoctor-tabs.css 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
@@ -79,4 +79,4 @@ p#release + #container {
     display: block;
     width: 100%;
   }
-}
+}
diff --git a/jekyll-assets/scripts/asciidoctor-tabs.js b/jekyll-assets/scripts/asciidoctor-tabs.js
diff --git a/lib/doxygentoasciidoc b/lib/doxygentoasciidoc
