Add build-with-inputs.yml

- Update docs

.github/workflows/build-with-inputs.yml

@@ -0,0 +1,123 @@
+name: 'Build with inputs'
+on:
+  workflow_dispatch:
+    inputs:
+      board:
+        description: 'Board'
+        required: true
+        default: 'nice_nano'
+      shield:
+        description: 'Shield'
+        required: false
+        default: 'corne_left'
+      alphas:
+        description: 'Miryoku Alphas'
+        required: false
+        default: ''
+      nav:
+        description: 'Miryoku Nav'
+        required: false
+        default: ''
+      clipboard:
+        description: 'Miryoku Clipboard'
+        required: false
+        default: ''
+      layers:
+        description: 'Miryoku Layers'
+        required: false
+        default: ''
+      mapping:
+        description: 'Miryoku Mapping'
+        required: false
+        default: ''
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    container:
+      image: zmkfirmware/zmk-build-arm:2.4
+    strategy:
+      fail-fast: false
+    steps:
+      - name: Check inputs
+        run: |
+          echo "board: ${{ github.event.inputs.board }}"
+          echo "shield: ${{ github.event.inputs.shield }}"
+          echo "alphas: ${{ github.event.inputs.alphas }}"
+          echo "nav: ${{ github.event.inputs.nav }}"
+          echo "clipboard: ${{ github.event.inputs.clipboard }}"
+          echo "layers: ${{ github.event.inputs.layers }}"
+          echo "mapping: ${{ github.event.inputs.mapping }}"
+      - name: Checkout
+        uses: actions/checkout@v2
+      - name: Cache west modules
+        uses: actions/cache@v2
+        env:
+          cache-name: cache-zephyr-modules
+        with:
+          path: |
+            bootloader/
+            modules/
+            tools/
+            zephyr/
+            zmk/
+          key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ hashFiles('config/west.yml') }}
+          restore-keys: |
+            ${{ runner.os }}-build-${{ env.cache-name }}-
+            ${{ runner.os }}-build-
+            ${{ runner.os }}-
+        timeout-minutes: 2
+        continue-on-error: true
+      - name: Initialize workspace (west init)
+        run: west init -l config
+      - name: Update modules (west update)
+        run: west update
+      - name: Export Zephyr CMake package (west zephyr-export)
+        run: west zephyr-export
+      - name: Process variables
+        id: variables
+        run: |
+          if [ -n "${{ github.event.inputs.shield }}" ]
+          then
+            SHIELD_ARG="-DSHIELD=${{ github.event.inputs.shield }}"
+          fi
+          echo "::set-output name=shield-arg::${SHIELD_ARG}"
+          configfile="${GITHUB_WORKSPACE}/miryoku/config.h"
+          echo '// https://github.com/manna-harbour/miryoku-zmk/' > "$configfile"
+          echo "::set-output name=configfile::$configfile"
+          artifact_build_name="miryoku_zmk ${{ github.event.inputs.shield }} ${{ github.event.inputs.board }}"
+          for option in "alphas_${{ github.event.inputs.alphas }}" "nav_${{ github.event.inputs.nav }}" "clipboard_${{ github.event.inputs.clipboard }}" "layers_${{ github.event.inputs.layers }}" "mapping_${{ github.event.inputs.mapping }}"
+          do
+            case "$option" in
+              *_ ) ;;
+              * )
+                artifact_build_name="$artifact_build_name $option"
+                echo "#define MIRYOKU_"`echo "$option" | tr 'a-z' 'A-Z'` >> "$configfile"
+                ;;
+            esac
+          done
+          artifact_build_name=`echo $artifact_build_name | tr ' ' '-'`
+          echo "::set-output name=artifact-build-name::$artifact_build_name"
+          echo "::set-output name=artifact-generic-name::$artifact_build_name"
+          echo "::set-output name=artifact-dir::artifacts"
+      - name: Build (west build)
+        run: west build -s zmk/app -b ${{ github.event.inputs.board }} -- ${{ steps.variables.outputs.shield-arg }} -DZMK_CONFIG="${GITHUB_WORKSPACE}/config"
+      - name: Prepare artifacts
+        run: |
+          mkdir ${{ steps.variables.outputs.artifact-dir }}
+          cp "${{ steps.variables.outputs.configfile }}" "${{ steps.variables.outputs.artifact-dir }}"
+          for extension in "hex" "uf2"
+          do
+            file="build/zephyr/zmk.$extension"
+            if [ -f "$file" ]
+            then
+              cp "$file" "${{ steps.variables.outputs.artifact-dir }}/${{ steps.variables.outputs.artifact-build-name }}.$extension"
+            fi
+          done
+      - name: Archive artifacts
+        uses: actions/upload-artifact@v2
+        with:
+          name: ${{ steps.variables.outputs.artifact-generic-name }}
+          path: ${{ steps.variables.outputs.artifact-dir }}
+        continue-on-error: true
+
+

readme.org

@@ -5,15 +5,54 @@
 [[https://github.com/manna-harbour/miryoku/][Miryoku]] is an ergonomic, minimal, orthogonal, and universal keyboard layout.  This is the miryoku implementation for [[https://zmkfirmware.dev/][ZMK]].
 
 * Contents                                                              :TOC_1:
+- [[#building][Building]]
 - [[#miryoku-keymap][Miryoku Keymap]]
 - [[#configuration-options][Configuration Options]]
 - [[#config-file][Config File]]
 - [[#example-config-file][Example Config File]]
 - [[#mapping][Mapping]]
 - [[#keyboard-keymaps][Keyboard Keymaps]]
-- [[#prebuilt-firmware][Prebuilt Firmware]]
 - [[#contact][Contact]]
 
+* Building
+
+
+** Supported Keyboards
+
+
+*** Board Only
+
+Any [[https://github.com/zmkfirmware/zmk/tree/main/app/boards/arm][board supported by ZMK]] with a [[#keyboard-keymaps][keymap in Miryoku ZMK]].
+
+
+*** Board / Shield Combination
+
+Any compatible combination of [[https://github.com/zmkfirmware/zmk/tree/main/app/boards/arm][board supported by ZMK]] and [[https://github.com/zmkfirmware/zmk/tree/main/app/boards/shields][shield supported by ZMK]] with a [[#keyboard-keymaps][keymap in Miryoku ZMK]].
+
+
+** Local Builds
+
+Clone this repo and use for [[https://zmk.dev/docs/development/build-flash#building-from-zmk-config-folder][ZMK_CONFIG]].
+
+
+** GitHub Actions Workflows
+
+
+*** Prebuilt Firmware
+
+Some prebuilt firmware can be downloaded from the repo.  Log in to GitHub, visit the [[https://github.com/manna-harbour/zmk-config/actions][Actions]] tab, select the appropriate workflow, select the latest successful workflow run, select the desired artifact, and unzip the downloaded zip file.
+
+
+*** Inputs
+
+Fork this repo, select the [[https://github.com/manna-harbour/zmk-config/actions/workflows/build-with-inputs.yml][Build with inputs]] workflow action, select Run workflow, fill out the form with a [[#Supported-Keyboards][supported keyboard]] and [[#configuration-options][configuration options]], activate Run workflow, wait for successful completion, select the workflow run, select the Artifacts, and unzip the downloaded zip file.
+
+
+*** Customise Workflow Files
+
+Fork this repo and edit the included workflow files with [[#Supported-Keyboards][supported keyboards]] and [[#configuration-options][configuration options]].
+
+
 * Miryoku Keymap
 
 The miryoku keymap is a ZMK DT keymap file using C preprocessor macros for [[#configuration-options][configuration options]] and to abstract the physical layout.  The file is [[./miryoku/miryoku.dtsi][miryoku/miryoku.dtsi]].  The file is included into the [[#keyboard-keymaps][keyboard's keymap]] with
@@ -25,12 +64,23 @@ The miryoku keymap is a ZMK DT keymap file using C preprocessor macros for [[#co
 
 * Configuration Options
 
-[[https://github.com/manna-harbour/miryoku/blob/master/src/babel/readme.org#keymap-configuration-options][Keymap configuration options]] and [[#mapping][mapping]] configuration options are given in the documentation in the form ~option=value~.  To use configuration options in Miryoku ZMK, convert to the form ~#define option_value~.  To apply the configuration options to all builds add them to the [[#config-file][config file]].  To apply configuration options to a single keyboard, add them to the [[#keyboard-keymaps][keyboard keymap]] file before any ~#include~ lines.
+[[https://github.com/manna-harbour/miryoku/blob/master/src/babel/readme.org#keymap-configuration-options][Keymap configuration options]] and [[#mapping][mapping]] configuration options are given in the documentation in the form ~option=value~.
+
+
+** Configuration Options in Config File
+
+Convert to the form ~#define option_value~.  To apply the configuration options to all builds add them to the [[#config-file][config file]].  To apply configuration options to a single keyboard, add them to the [[#keyboard-keymaps][keyboard keymap]] file before any ~#include~ lines.
+
+
+** Configuration Options in GitHub Actions Workflows
+
+
+Convert to the form ~value~ (uppercase or lowercase) and use with the corresponding ~option~ [[#Customise-Workflow-Files][matrix variable]] or [[#Inputs][input]].  Empty fields will use the default value.
 
 
 * Config File
 
-The config file can be used to provide [[#configuration-options][configuration options]] for all keyboard builds.  The file is [[./miryoku/config.h][miryoku/config.h]].  See the [[#example-config-file][example config file]].
+The config file can be used to provide [[#configuration-options][configuration options]] for all [[#Local-Builds][local builds]].  The file is [[./miryoku/config.h][miryoku/config.h]].  See the [[#example-config-file][example config file]].
 
 
 * Example Config File
@@ -99,8 +149,6 @@ compatibility
 
 ~MIRYOKU_MAPPING=EXTENDED_THUMBS~
 
-[[https://raw.githubusercontent.com/manna-harbour/miryoku/master/data/mapping/miryoku-kle-mapping-ortho_4x12-extended_thumbs.png]]
-
 
 *** 50-kyria
 
@@ -136,18 +184,11 @@ compatibility
 
 Keymap files for many keyboards included in ZMK are provided in [[./config/][config/]].
 
-
-* Prebuilt Firmware
-
-Prebuilt firmware can be downloaded from the repo.  Log in to GitHub, visit the [[https://github.com/manna-harbour/miryoku-zmk/actions][Actions]] tab, select the appropriate workflow, select the latest successful workflow run, select the desired artifact, and unzip the downloaded zip file.
-
-
 * Contact
 
-For issues with the code, including requests for any of the following, please [[https://github.com/manna-harbour/miryoku-zmk/issues/new][create an issue]]. Pull requests are also welcome.
+For feature requests or issues with code or documentation please
+[[https://github.com/manna-harbour/zmk-config/issues/new][open an issue]].
 
-- Additional mapping and keyboard keymap files
+For more general discussion please [[https://github.com/manna-harbour/manna-harbour/tree/main/contact][contact Manna Harbour]].
-- Additional mapping configuration options (see miryoku QMK for examples)
-- Populating unused keys in ~MIRYOKU_MAPPING_TAP~ (currently skipped for some mapping files)
 
 [[https://github.com/manna-harbour][https://raw.githubusercontent.com/manna-harbour/miryoku/master/data/logos/manna-harbour-boa-32.png]]