Merge branch 'develop' into led-drivers-documentation

.github/workflows/docs.yml

@@ -7,14 +7,18 @@ on:
   push:
     branches:
     - master
-    - vitepress
     paths:
     - 'builddefs/docsgen/**'
     - 'tmk_core/**'
     - 'quantum/**'
     - 'platforms/**'
     - 'docs/**'
     - '.github/workflows/docs.yml'
+  pull_request:
+    paths:
+    - 'builddefs/docsgen/**'
+    - 'docs/**'
+    - '.github/workflows/docs.yml'
 
 defaults:
   run:
@@ -25,61 +29,37 @@ jobs:
     runs-on: ubuntu-latest
     container: ghcr.io/qmk/qmk_cli
 
-    # protect against those who develop with their fork on master
-    if: github.repository == 'qmk/qmk_firmware' || (github.repository == 'tzarc/qmk_firmware' && github.ref == 'refs/heads/vitepress')
-
     steps:
     - uses: actions/checkout@v4
       with:
         fetch-depth: 1
 
     - name: Install dependencies
       run: |
-        apt-get update && apt-get install -y rsync doxygen curl
+        apt-get update && apt-get install -y rsync doxygen
         # install nvm
         touch $HOME/.bashrc
-        curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
+        wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
 
     - name: Install node
       run: |
         source $HOME/.bashrc
         nvm install 20
         nvm use 20
         corepack enable
-        npm install -g moxygen
 
     - name: Build docs
       run: |
         source $HOME/.bashrc
         nvm use 20
         qmk --verbose generate-docs
-        touch '.build/docs/.nojekyll'
-
-    - name: Set CNAME
-      if: github.repository == 'qmk/qmk_firmware'
-      run: |
-        # Override target CNAME
-        echo 'docs.qmk.fm' > .build/docs/CNAME
-
-    - name: Override CNAME
-      if: github.repository == 'tzarc/qmk_firmware'
-      run: |
-        # Temporarily override target CNAME during development
-        echo 'vitepress.qmk.fm' > .build/docs/CNAME
 
     - name: Deploy
-      if: github.repository == 'qmk/qmk_firmware'
+      if: ${{ github.event_name == 'push' && github.repository == 'qmk/qmk_firmware' }}
       uses: JamesIves/[email protected]
       with:
           token: ${{ secrets.GITHUB_TOKEN }}
           branch: gh-pages
           folder: .build/docs
           git-config-name: QMK Bot
           git-config-email: [email protected]
-
-    - name: Deploy
-      if: github.repository == 'tzarc/qmk_firmware'
-      uses: JamesIves/[email protected]
-      with:
-        branch: gh-pages
-        folder: .build/docs

Makefile

@@ -465,3 +465,18 @@ distclean_userspace: clean
 	rm -f $(QMK_USERSPACE)/*.bin $(QMK_USERSPACE)/*.hex $(QMK_USERSPACE)/*.uf2
 	echo 'done.'
 endif
+
+# Extra targets for formatting and/or pytest, running within the qmk/qmk_cli container to match GHA.
+CONTAINER_PREAMBLE := export HOME="/tmp"; export PATH="/tmp/.local/bin:\$$PATH"; python3 -m pip install --upgrade pip; python3 -m pip install -r requirements-dev.txt
+
+.PHONY: format-core
+format-core:
+	RUNTIME=docker ./util/docker_cmd.sh bash -lic "$(CONTAINER_PREAMBLE); qmk format-c --core-only -a && qmk format-python -a"
+
+.PHONY: pytest
+pytest:
+	RUNTIME=docker ./util/docker_cmd.sh bash -lic "$(CONTAINER_PREAMBLE); qmk pytest"
+
+.PHONY: format-and-pytest
+format-and-pytest:
+	RUNTIME=docker ./util/docker_cmd.sh bash -lic "$(CONTAINER_PREAMBLE); qmk format-c --core-only -a && qmk format-python -a && qmk pytest"

builddefs/docsgen/.vitepress/theme/QMKLayout.vue

@@ -2,11 +2,22 @@
 import DefaultTheme from 'vitepress/theme'
 import { useRouter } from 'vitepress'
 import { onBeforeMount } from 'vue';
+import aliases from "../../../../docs/_aliases.json";
 
 const router = useRouter()
 onBeforeMount(async () => {
-    if (window.location.href.includes('/#/')) {
-        const newUrl = window.location.href.replace(/\/#\//, '/').replace(/\?id=/, '#');
+    // Convert from docsify-style to vitepress-style URLs
+    let newUrl = window.location.href.replace(/\/#\//, '/').replace(/\?id=/, '#');
+
+    // Convert any aliases
+    let testUrl = new URL(newUrl);
+    while (testUrl.pathname in aliases) {
+        testUrl.pathname = aliases[testUrl.pathname];
+    }
+    newUrl = testUrl.toString();
+
+    // Redirect if required
+    if (newUrl != window.location.href) {
         window.history.replaceState({}, '', newUrl);
         await router.go(newUrl);
     }

docs/ChangeLog/20240526.md

@@ -109,6 +109,16 @@ Essentially, changes were made in the internals of how QMK interacts with USB fo
 
 Compliance checks were run against QMK firmwares for the most popular ARM microcontrollers, as well as suspend/resume tests. As far as we can tell, a whole host of hard-to-reproduce issues are mitigated by this change.
 
+## Deprecation Notices
+
+In line with the [notice period](../support_deprecation_policy#how-much-advance-notice-will-be-given), deprecation notices for larger items are listed here.
+
+### Migration of VIA keymaps to VIA team control
+
+The QMK team has been in discussion with the VIA maintainers and all VIA-related keymaps in the `qmk_firmware` repository will transition to a `qmk_userspace`-style repository under the VIA team's control at the end of the next breaking changes period. This allows the VIA team to support many more custom keyboard configurations, as well as reduces the turnaround time for any changes to the VIA protocol they wish to make.
+
+At the end of the breaking changes cycle ending 2024-08-25, VIA-enabled keymaps will no longer be accepted into the QMK repository. At the time of migration, any open PRs against `qmk_firmware` which include new VIA-related keymaps will be subsequently be asked to remove those keymaps and instead raise a PR against the userspace repository containing all VIA keymaps.
+
 ## Full changelist {#full-changelist}
 
 Core:

docs/_aliases.json

@@ -0,0 +1,74 @@
+{
+    "/adding_a_keyboard_to_qmk": "/hardware_keyboard_guidelines",
+    "/build_environment_setup": "/newbs_getting_started",
+    "/cli_dev_configuration": "/cli_configuration",
+    "/dynamic_macros": "/feature_dynamic_macros",
+    "/feature_common_shortcuts": "/feature_advanced_keycodes",
+    "/getting_started_build_tools": "/newbs_getting_started",
+    "/getting_started_getting_help": "/support",
+    "/glossary": "/reference_glossary",
+    "/key_lock": "/feature_key_lock",
+    "/make_instructions": "/getting_started_make_guide",
+    "/python_development": "/cli_development",
+    "/space_cadet_shift": "/feature_space_cadet_shift",
+    "/tap_dance": "/feature_tap_dance",
+    "/tutorial": "/newbs",
+    "/unicode": "/feature_unicode",
+
+    "/adc_driver": "/drivers/adc",
+    "/apa102_driver": "/drivers/apa102",
+    "/audio_driver": "/drivers/audio",
+    "/eeprom_driver": "/drivers/eeprom",
+    "/feature_audio": "/features/audio",
+    "/feature_auto_shift": "/features/auto_shift",
+    "/feature_autocorrect": "/features/autocorrect",
+    "/feature_backlight": "/features/backlight",
+    "/feature_bluetooth": "/features/bluetooth",
+    "/feature_bootmagic": "/features/bootmagic",
+    "/feature_caps_word": "/features/caps_word",
+    "/feature_combo": "/features/combo",
+    "/feature_command": "/features/command",
+    "/feature_digitizer": "/features/digitizer",
+    "/feature_dip_switch": "/features/dip_switch",
+    "/feature_dynamic_macros": "/features/dynamic_macros",
+    "/feature_encoders": "/features/encoders",
+    "/feature_grave_esc": "/features/grave_esc",
+    "/feature_haptic_feedback": "/features/haptic_feedback",
+    "/feature_hd44780": "/features/hd44780",
+    "/feature_joystick": "/features/joystick",
+    "/feature_key_lock": "/features/key_lock",
+    "/feature_key_overrides": "/features/key_overrides",
+    "/feature_leader_key": "/features/leader_key",
+    "/feature_led_indicators": "/features/led_indicators",
+    "/feature_led_matrix": "/features/led_matrix",
+    "/feature_midi": "/features/midi",
+    "/feature_mouse_keys": "/features/mouse_keys",
+    "/feature_oled_driver": "/features/oled_driver",
+    "/feature_os_detection": "/features/os_detection",
+    "/feature_pointing_device": "/features/pointing_device",
+    "/feature_programmable_button": "/features/programmable_button",
+    "/feature_ps2_mouse": "/features/ps2_mouse",
+    "/feature_rawhid": "/features/rawhid",
+    "/feature_repeat_key": "/features/repeat_key",
+    "/feature_rgb_matrix": "/features/rgb_matrix",
+    "/feature_rgblight": "/features/rgblight",
+    "/feature_secure": "/features/secure",
+    "/feature_send_string": "/features/send_string",
+    "/feature_sequencer": "/features/sequencer",
+    "/feature_space_cadet": "/features/space_cadet",
+    "/feature_split_keyboard": "/features/split_keyboard",
+    "/feature_st7565": "/features/st7565",
+    "/feature_stenography": "/features/stenography",
+    "/feature_swap_hands": "/features/swap_hands",
+    "/feature_tap_dance": "/features/tap_dance",
+    "/feature_tri_layer": "/features/tri_layer",
+    "/feature_unicode": "/features/unicode",
+    "/feature_wpm": "/features/wpm",
+    "/flash_driver": "/drivers/flash",
+    "/gpio_control": "/drivers/gpio",
+    "/i2c_driver": "/drivers/i2c",
+    "/serial_driver": "/drivers/serial",
+    "/spi_driver": "/drivers/spi",
+    "/uart_driver": "/drivers/uart",
+    "/ws2812_driver": "/drivers/ws2812"
+}

docs/_sidebar.json

@@ -212,7 +212,8 @@
                         "text": "Most Recent ChangeLog",
                         "link": "/ChangeLog/20240526"
                     },
-                    { "text": "Past Breaking Changes", "link": "/breaking_changes_history" }
+                    { "text": "Past Breaking Changes", "link": "/breaking_changes_history" },
+                    { "text": "Deprecation Policy", "link": "/support_deprecation_policy" }
                 ]
             },
 

docs/drivers/eeprom.md

@@ -119,13 +119,14 @@ This driver performs writes to the embedded flash storage embedded in the MCU. I
 
 Configurable options in your keyboard's `config.h`:
 
-`config.h` override                      | Default     | Description
------------------------------------------|-------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
-`#define WEAR_LEVELING_EFL_FIRST_SECTOR` | _unset_            | The first sector on the MCU to use. By default this is not defined and calculated at runtime based on the MCU. However, different flash sizes on MCUs may require custom configuration.
-`#define WEAR_LEVELING_EFL_FLASH_SIZE`   | _unset_            | Allows overriding the flash size available for use for wear-leveling. Under normal circumstances this is automatically calculated and should not need to be overridden. Specifying a size larger than the amount actually available in flash will usually prevent the MCU from booting.
-`#define WEAR_LEVELING_LOGICAL_SIZE`     | `(backing_size/2)` | Number of bytes "exposed" to the rest of QMK and denotes the size of the usable EEPROM.
-`#define WEAR_LEVELING_BACKING_SIZE`     | `2048`             | Number of bytes used by the wear-leveling algorithm for its underlying storage, and needs to be a multiple of the logical size.
-`#define BACKING_STORE_WRITE_SIZE`       | _automatic_        | The byte width of the underlying write used on the MCU, and is usually automatically determined from the selected MCU family. If an error occurs in the auto-detection, you'll need to consult the MCU's datasheet and determine this value, specifying it directly.
+`config.h` override                                | Default            | Description
+---------------------------------------------------|--------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+`#define WEAR_LEVELING_EFL_FIRST_SECTOR`           | _unset_            | The first sector on the MCU to use. By default this is not defined and calculated at runtime based on the MCU. However, different flash sizes on MCUs may require custom configuration.
+`#define WEAR_LEVELING_EFL_FLASH_SIZE`             | _unset_            | Allows overriding the flash size available for use for wear-leveling. Under normal circumstances this is automatically calculated and should not need to be overridden. Specifying a size larger than the amount actually available in flash will usually prevent the MCU from booting.
+`#define WEAR_LEVELING_EFL_OMIT_LAST_SECTOR_COUNT` | `0`                | Number of sectors to omit at the end of the flash. These sectors will not be allocated to the driver and the usable flash block will be offset, but keeping the set flash size. Useful on devices with bootloaders requiring a check flag at the end of flash to be present in order to confirm a valid, bootable firmware.
+`#define WEAR_LEVELING_LOGICAL_SIZE`               | `(backing_size/2)` | Number of bytes "exposed" to the rest of QMK and denotes the size of the usable EEPROM.
+`#define WEAR_LEVELING_BACKING_SIZE`               | `2048`             | Number of bytes used by the wear-leveling algorithm for its underlying storage, and needs to be a multiple of the logical size.
+`#define BACKING_STORE_WRITE_SIZE`                 | _automatic_        | The byte width of the underlying write used on the MCU, and is usually automatically determined from the selected MCU family. If an error occurs in the auto-detection, you'll need to consult the MCU's datasheet and determine this value, specifying it directly.
 
 ::: warning
 If your MCU does not boot after swapping to the EFL wear-leveling driver, it's likely that the flash size is incorrectly detected, usually as an MCU with larger flash and may require overriding.