Merge pull request #3592 from raspberrypi/develop

Update deployed version of docs

README.md

@@ -60,6 +60,8 @@ And install the [Ruby bundler](https://bundler.io/):
 $ gem install bundler
 ```
 
+If you're using a system version of Python 3.12, you may also need to run the Python 3.12 certificate-installation script. Find the Python3.12 folder on your machine, and run `Install Certificates.command`.
+
 ##### Set up Homebrew Version of Ruby
 
 Because macOS provides its own version of Ruby, Homebrew doesn't automatically set up symlinks to access the version you just installed with the `ruby` command. But after a successful install, Homebrew outputs the commands you'll need to run to set up the symlink yourself. If you use the default macOS `zsh` shell on Apple Silicon, you can set up the symlink with the following command:

documentation/asciidoc/computers/getting-started/configuring.adoc

@@ -48,9 +48,9 @@ By default, older versions of Raspberry Pi OS set the username to "pi". If you u
 
 image::images/initial-setup/user.png[alt="Create your username and password."]
 
-=== WiFi
+=== Wi-Fi
 
-This page helps you connect to a WiFi network. Choose your preferred network from the list.
+This page helps you connect to a Wi-Fi network. Choose your preferred network from the list.
 
 image::images/initial-setup/network.png[alt="Selecting a wireless network."]
 

documentation/asciidoc/computers/getting-started/install.adoc

@@ -64,19 +64,19 @@ If you don't configure your Raspberry Pi via OS customisation settings, Raspberr
 The OS customisation menu lets you set up your Raspberry Pi before first boot. You can preconfigure:
 
 * a username and password
-* WiFi credentials
+* Wi-Fi credentials
 * the device hostname
 * the time zone
 * your keyboard layout
 * remote connectivity
 
-When you first open the OS customisation menu, you might see a prompt asking for permission to load WiFi credentials from your host computer. If you respond "yes", Imager will prefill WiFi credentials from the network you're currently connected to. If you respond "no", you can enter WiFi credentials manually.
+When you first open the OS customisation menu, you might see a prompt asking for permission to load Wi-Fi credentials from your host computer. If you respond "yes", Imager will prefill Wi-Fi credentials from the network you're currently connected to. If you respond "no", you can enter Wi-Fi credentials manually.
 
 The **hostname** option defines the hostname your Raspberry Pi broadcasts to the network using https://en.wikipedia.org/wiki/Multicast_DNS[mDNS]. When you connect your Raspberry Pi to your network, other devices on the network can communicate with your computer using `<hostname>.local` or `<hostname>.lan`.
 
 The **username and password** option defines the username and password of the admin user account on your Raspberry Pi.
 
-The **wireless LAN** option allows you to enter an SSID (name) and password for your wireless network. If your network does not broadcast an SSID publicly, you should enable the "Hidden SSID" setting. By default, Imager uses the country you're currently in as the "Wireless LAN country". This setting controls the WiFi broadcast frequencies used by your Raspberry Pi. Enter credentials for the wireless LAN option if you plan to run a headless Raspberry Pi.
+The **wireless LAN** option allows you to enter an SSID (name) and password for your wireless network. If your network does not broadcast an SSID publicly, you should enable the "Hidden SSID" setting. By default, Imager uses the country you're currently in as the "Wireless LAN country". This setting controls the Wi-Fi broadcast frequencies used by your Raspberry Pi. Enter credentials for the wireless LAN option if you plan to run a headless Raspberry Pi.
 
 The **locale settings** option allows you to define the time zone and default keyboard layout for your Pi. 
 
@@ -124,9 +124,7 @@ Next, proceed to the xref:getting-started.adoc#configuration-on-first-boot[first
 
 Network Install enables a Raspberry Pi to install an operating system on a storage device using a version of Raspberry Pi Imager downloaded over the network. With Network Install, you can get an operating system installed on your Raspberry Pi with no separate SD card reader and no computer other than your Raspberry Pi. You can run Network Install on any compatible storage device, including SD cards and USB storage.
 
-Network Install only runs on Raspberry Pi 4, 400. If your Raspberry Pi runs an older bootloader, you may need to xref:raspberry-pi.adoc#bootloader_update_stable[update the bootloader] to use Network Install.
-
-IMPORTANT: Currently, Network Install is not available on Raspberry Pi 5. Support will be added in a future bootloader update.
+Network Install only runs on Raspberry Pi 4, 400, and 5. If your Raspberry Pi runs an older bootloader, you may need to xref:raspberry-pi.adoc#bootloader_update_stable[update the bootloader] to use Network Install.
 
 ////
 TODO: Update this video for the new Imager look & flow video::b1SYVpM9lto[youtube]

documentation/asciidoc/computers/getting-started/setting-up.adoc

@@ -92,8 +92,6 @@ image:images/peripherals/cable-mouse.png[alt="Plugging a mouse into a Raspberry
 
 === Display
 
-If your Raspberry Pi has more than one HDMI port, plug your primary monitor into the port marked `HDMI0`.
-
 Raspberry Pi models have the following display connectivity:
 
 [%header,cols="1,1"]
@@ -117,14 +115,16 @@ Raspberry Pi models have the following display connectivity:
 |HDMI, audio and composite out via 3.5mm http://en.wikipedia.org/wiki/Phone_connector_(audio)#TRRS_standards[TRRS] jack
 
 |Raspberry Pi 1 Model A+
-|HDMI, RCA connector
+|HDMI, audio and composite out via 3.5mm http://en.wikipedia.org/wiki/Phone_connector_(audio)#TRRS_standards[TRRS] jack
 
 |Raspberry Pi Zero (all models)
 |mini HDMI
 |===
 
 NOTE: No Raspberry Pi models support video over USB-C (DisplayPort alt mode).
 
+If your Raspberry Pi has more than one HDMI port, plug your primary monitor into the port marked `HDMI0`.
+
 Most displays don't have micro or mini HDMI ports. However, you can use a https://www.raspberrypi.com/products/micro-hdmi-to-standard-hdmi-a-cable/[micro-HDMI-to-HDMI cable] or https://www.raspberrypi.com/products/standard-hdmi-a-male-to-mini-hdmi-c-male-cable/[mini-HDMI-to-HDMI cable] to connect those ports on your Raspberry Pi to any HDMI display. For displays that don't support HDMI, consider an adapter that translates display output from HDMI to a port supported by your display.
 
 image::images/peripherals/cable-hdmi.png[alt="Plugging a micro HDMI cable into a Raspberry Pi."]
@@ -137,7 +137,7 @@ All variants of the Raspberry Pi 1, 2, 3, and 4 include a 3.5mm auxiliary http:/
 
 === Networking
 
-The following Raspberry Pi models come with WiFi and Bluetooth connectivity:
+The following Raspberry Pi models come with Wi-Fi and Bluetooth connectivity:
 
 * Raspberry Pi 5
 * Raspberry Pi 4

documentation/asciidoc/computers/raspberry-pi/boot-eeprom-rpi4.adoc

@@ -2,7 +2,7 @@
 
 Raspberry Pi 5, Raspberry Pi 4, 400, Compute Module 4, and Compute Module 4S computers use an EEPROM to boot the system. All other models of Raspberry Pi computer use the `bootcode.bin` file located in the boot filesystem.
 
-NOTE: The scripts and pre-compiled binaries used to create the `rpi-eeprom` package which is used to update the Raspberry Pi 4 bootloader and VLI USB controller EEPROMs is available https://github.com/raspberrypi/rpi-eeprom/[on GitHub].
+NOTE: You can find the scripts and pre-compiled binaries used to create `rpi-eeprom`  in the https://github.com/raspberrypi/rpi-eeprom/[rpi-eeprom GitHub repository].
 
 === Boot diagnostics
 

documentation/asciidoc/computers/raspberry-pi/bootflow-legacy.adoc

@@ -1,6 +1,6 @@
 == Boot sequence
 
-IMPORTANT: The following boot sequence applies to the BCM2837 and BCM2837B0 based models of Raspberry Pi only. On models prior to this, the Raspberry Pi will try SD card boot, followed by xref:raspberry-pi.adoc#usb-device-boot-mode[USB device mode boot]. For the Raspberry Pi 4 and Raspberry Pi 5 boot sequence please see the xref:raspberry-pi.adoc#raspberry-pi-4-and-raspberry-pi-5-boot-flow[Raspberry Pi boot flow] section.
+IMPORTANT: The following boot sequence applies to the BCM2837 and BCM2837B0 based models of Raspberry Pi only. On models prior to this, the Raspberry Pi will try SD card boot, followed by xref:raspberry-pi.adoc#usb-device-boot-mode[USB device mode boot]. For the Raspberry Pi 4 and Raspberry Pi 5 boot sequence please see the xref:raspberry-pi.adoc#raspberry-pi-4-and-raspberry-pi-5-boot-flow[Raspberry Pi 4 and Raspberry Pi 5 boot flow] section.
 
 USB boot defaults on Raspberry Pi 3 will depend on which version is being used. See this xref:raspberry-pi.adoc#usb-mass-storage-boot[page] for information on enabling USB boot modes when not enabled by default.
 

documentation/asciidoc/computers/raspberry-pi/power-supplies.adoc

@@ -12,13 +12,17 @@ NOTE: No Raspberry Pi models support USB-PPS.
 
 NOTE: If you use a third-party USB-PD multi-port power supply, plugging an additional device into the supply when your Raspberry Pi is connected causes a renegotiation between the supply and the Raspberry Pi. If the Raspberry Pi is powered, this happens seamlessly. If the Raspberry Pi is powered down, this renegotiation may cause the Raspberry Pi to boot.
 
-== Power over Ethernet (PoE) connector
-
-The Ethernet jack on Raspberry Pi 5 is PoE+ capable, supporting the IEEE 802.3at-2009 PoE standard. The Raspberry Pi 5 has a 4-pin Power-over-Ethernet (PoE) header block, located between the Ethernet jack and the two MIPI connectors.
+=== Power over Ethernet (PoE) connector
 
 .Raspberry Pi 5 PoE header
 image::images/poe.jpg[alt="The PoE connector,width="70%"]
 
+The Ethernet jack on Raspberry Pi 5 is PoE+ capable, supporting the IEEE 802.3at-2009 PoE standard.
+
+The Ethernet jack on Raspberry Pi 4B and Pi 3B+ is PoE capable, supporting the IEEE 802.3af-2003 PoE standard.
+
+All Raspberry Pi models with a PoE-capable Ethernet jack require a HAT to draw power through the Ethernet port. For models that support PoE, we recommend the https://www.raspberrypi.com/products/poe-hat/[PoE HAT]. For models that support PoE+, we recommend the https://www.raspberrypi.com/products/poe-plus-hat/[PoE+ HAT].
+
 === Typical power requirements
 
 |===

documentation/asciidoc/computers/remote-access/find-your-ip-address.adoc

@@ -7,7 +7,7 @@ To find the local IP address of your Raspberry Pi, use one of the following meth
 
 Hover over the network icon in the system tray, and a tooltip will appear. This tooltip displays the name of the network you're currently connected to and your IP address.
 
-image::images/network-tooltip.png[the Network Manager tooltip displaying a WiFi network name and IP address]
+image::images/network-tooltip.png[the Network Manager tooltip displaying a Wi-Fi network name and IP address]
 
 ==== Command line
 

documentation/asciidoc/microcontrollers/debug-probe/updating-firmware.adoc

@@ -1,10 +1,15 @@
 == Updating the firmware on the Debug Probe
 
-NOTE: The current version of the Debug Probe firmware is version 1.0.3. If you're running an older version, or if you have accidentally overwritten the firmware on your Debug Probe, the latest release of the firmware can be found on https://github.com/raspberrypi/debugprobe/releases/latest[GitHub].
+Firmware for the Debug Probe is available as a UF2 file distributed by Raspberry Pi.
 
-From time to time you may need to update the Debug Probe firmware. New firmware for the probe will be made available as a UF2 file distributed by Raspberry Pi.
+The latest version of the Debug Probe firmware is version 2. If you're running an older version, or if you have accidentally overwritten the firmware on your Debug Probe, you can find the latest release of the firmware in https://github.com/raspberrypi/debugprobe/releases/latest[the debugprobe GitHub repository].
 
-Pinch to remove the top of the Debug Probe enclosure, then push and hold the BOOTSEL button as you plug the Debug Probe into your computer. This will mount an RPI-RP2 volume on your desktop. Drag-and-drop the firmware UF2 onto the RPI-RP2 volume. The firmware will be copied to the Debug Probe and the volume will dismount.
+Download `debugprobe.uf2` from the latest release.
 
-Your Debug Probe will reboot. You are now running an updated version of the Debug Probe firmware.
+Pinch to remove the top of the Debug Probe enclosure.
 
+Push and hold the BOOTSEL button as you plug the Debug Probe into your computer to mount a volume called "RPI-RP2".
+
+Copy `debugprobe.uf2` onto the "RPI-RP2" volume. The volume will dismount automatically after the file finishes copying onto the device.
+
+Your Debug Probe will reboot and now runs an updated version of the Debug Probe firmware. It is now ready for debugging.

documentation/asciidoc/microcontrollers/raspberry-pi-pico/utilities.adoc

@@ -8,10 +8,19 @@ If you have forgotten what has been programmed into your Raspberry Pi Pico, and
 
 === Debugging using another Raspberry Pi Pico
 
-It is possible to use one Raspberry Pi Pico to debug another Pico. This is possible via debugprobe, an application that allows a Pico to act as a USB → SWD and UART converter. This makes it easy to use a Pico on non-Raspberry Pi platforms such as Windows, Mac, and Linux computers where you don’t have GPIOs to connect directly to your Pico. Full instructions on how to use debugprobe to do this are available in our 'https://datasheets.raspberrypi.com/pico/getting-started-with-pico.pdf[getting started]' documentation.
+You can use one Raspberry Pi Pico to debug another Pico. This is possible via `debugprobe`, an application that allows a Pico to act as a USB → SWD and UART converter.
 
-* Download the https://github.com/raspberrypi/debugprobe/releases/latest/download/debugprobe_on_pico.uf2[UF2 file]
-* Go to the https://github.com/raspberrypi/debugprobe[Debug Probe Github repository]
+You can find the latest release of the firmware in https://github.com/raspberrypi/debugprobe/releases/latest[the debugprobe GitHub repository].
+
+Download `debugprobe_on_pico.uf2` from the latest release.
+
+Push and hold the BOOTSEL button as you plug the debugger Pico into your computer to mount a volume called "RPI-RP2".
+
+Copy `debugprobe_on_pico.uf2` onto the volume. The volume will dismount automatically after the file finishes copying onto the device.
+
+Your Pico will reboot and now runs an updated version of the `debugprobe` firmware. It is now ready for debugging.
+
+TIP: For instructions on how to use the debugger, see https://datasheets.raspberrypi.com/pico/getting-started-with-pico.pdf[Getting Started with Pico].
 
 === Resetting Flash memory
 

documentation/htaccess_extra.txt

@@ -24,5 +24,6 @@ RedirectMatch 302 "^/documentation/setup/" "/documentation/computers/getting-sta
 RedirectMatch 302 "^/documentation/usage/camera/" "/documentation/accessories/camera.html"
 RedirectMatch 302 "^/documentation/usage/" "/documentation/computers/os.html"
 RedirectMatch 302 "^/documentation/configuration/" "/documentation/computers/configuration.html"
+RedirectMatch 302 "^/documentation/computers/raspberry-pi-5.html" "/documentation/computers/raspberry-pi.html"
 </IfModule>
 

scripts/create_build_adoc.py

@@ -13,9 +13,9 @@ def check_no_markdown(filename):
         if re.search('```\n.*?\n```', asciidoc):
             raise Exception("{} uses triple-backticks for markup - please use four-hyphens instead".format(filename))
         # strip out code blocks
-        asciidoc = re.sub('----\n.*?\n----', '', asciidoc, flags=re.DOTALL)
+        asciidoc = re.sub(r'----\n.*?\n----', '', asciidoc, flags=re.DOTALL)
         # strip out pass-through blocks
-        asciidoc = re.sub('\+\+\+\+\n.*?\n\+\+\+\+', '', asciidoc, flags=re.DOTALL)
+        asciidoc = re.sub(r'\+\+\+\+\n.*?\n\+\+\+\+', '', asciidoc, flags=re.DOTALL)
         if re.search('(?:^|\n)#+', asciidoc):
             raise Exception("{} contains a Markdown-style header (i.e. '#' rather than '=')".format(filename))
         if re.search(r'(\[.+?\]\(.+?\))', asciidoc):
@@ -57,19 +57,19 @@ def check_no_markdown(filename):
         template_vars = {
             'github_edit_link': os.path.join(site_config['githuburl'], 'blob', site_config['githubbranch_edit'], src_adoc)
         }
-        edit_text = re.sub('{{\s*(\w+)\s*}}', lambda m: template_vars[m.group(1)], edit_template)
+        edit_text = re.sub(r'{{\s*(\w+)\s*}}', lambda m: template_vars[m.group(1)], edit_template)
 
     new_contents = ''
     seen_header = False
     with open(src_adoc) as in_fh:
         for line in in_fh.readlines():
-            if re.match('^=+ ', line) is not None:
+            if re.match(r'^=+ ', line) is not None:
                 if not seen_header:
                     seen_header = True
                     if github_edit is not None:
                         line += edit_text + "\n\n"
             else:
-                m = re.match('^(include::)(.+)(\[\]\n?)$', line)
+                m = re.match(r'^(include::)(.+)(\[\]\n?)$', line)
                 if m:
                     line = m.group(1) + os.path.join('{includedir}/{parentdir}', m.group(2)) + m.group(3)
             new_contents += line

scripts/create_build_adoc_include.py

@@ -12,9 +12,9 @@ def check_no_markdown(filename):
         if re.search('```\n.*?\n```', asciidoc):
             raise Exception("{} uses triple-backticks for markup - please use four-hyphens instead".format(filename))
         # strip out code blocks
-        asciidoc = re.sub('----\n.*?\n----', '', asciidoc, flags=re.DOTALL)
+        asciidoc = re.sub(r'----\n.*?\n----', '', asciidoc, flags=re.DOTALL)
         # strip out pass-through blocks
-        asciidoc = re.sub('\+\+\+\+\n.*?\n\+\+\+\+', '', asciidoc, flags=re.DOTALL)
+        asciidoc = re.sub(r'\+\+\+\+\n.*?\n\+\+\+\+', '', asciidoc, flags=re.DOTALL)
         if re.search('(?:^|\n)#+', asciidoc):
             raise Exception("{} contains a Markdown-style header (i.e. '#' rather than '=')".format(filename))
         if re.search(r'(\[.+?\]\(.+?\))', asciidoc):
@@ -37,13 +37,13 @@ def check_no_markdown(filename):
         template_vars = {
             'github_edit_link': os.path.join(site_config['githuburl'], 'blob', site_config['githubbranch_edit'], src_adoc)
         }
-        edit_text = re.sub('{{\s*(\w+)\s*}}', lambda m: template_vars[m.group(1)], edit_template)
+        edit_text = re.sub(r'{{\s*(\w+)\s*}}', lambda m: template_vars[m.group(1)], edit_template)
 
     with open(src_adoc) as in_fh:
         new_contents = ''
         seen_header = False
         for line in in_fh.readlines():
-            if re.match('^=+ ', line) is not None:
+            if re.match(r'^=+ ', line) is not None:
                 if not seen_header:
                     seen_header = True
                     if github_edit is not None:

tests/fixtures/_config.yml

@@ -0,0 +1,54 @@
+# Welcome to Jekyll!
+#
+# This config file is meant for settings that affect your whole blog, values
+# which you are expected to set up once and rarely edit after that. If you find
+# yourself editing this file very often, consider using Jekyll's data files
+# feature for the data you need to update frequently.
+#
+# For technical reasons, this file is *NOT* reloaded automatically when you use
+# 'bundle exec jekyll serve'. If you change this file, please restart the server process.
+
+# Site settings
+# These are used to personalize your new site. If you look in the HTML files,
+# you will see them accessed via {{ site.title }}, {{ site.email }}, and so on.
+# You can create any custom variable you would like, and they will be accessible
+# in the templates via {{ site.myvariable }}.
+title: Raspberry Pi Documentation
+description: >- # this means to ignore newlines until "baseurl:"
+  Raspberry Pi Documentation.
+baseurl: "/documentation" # the subpath of your site, e.g. /blog
+url: "" # the base hostname & protocol for your site, e.g. http://example.com
+githuburl: "https://github.com/raspberrypi/documentation/"
+githubbranch: master
+githubbranch_edit: develop
+
+# Build settings
+theme: minima
+plugins:
+  - jekyll-asciidoc
+  - jekyll-feed
+
+# this corresponds to ASCIIDOC_BUILD_DIR in Makefile
+source: build/jekyll
+
+# this corresponds to HTML_DIR in Makefile
+destination: documentation/html
+
+sass:
+    sass_dir: css
+    quiet_deps: true
+
+asciidoctor:
+    template_dir: build/jekyll/_templates
+
+# Exclude from processing.
+# The following items will not be processed, by default. Create a custom list
+# to override the default setting.
+# exclude:
+#   - Gemfile
+#   - Gemfile.lock
+#   - node_modules
+#   - vendor/bundle/
+#   - vendor/cache/
+#   - vendor/gems/
+#   - vendor/ruby/