Klipper3d · KevinOConnor · Jul 27, 2021 · Jul 21, 2021 · Jul 21, 2021 · Jul 26, 2021
diff --git a/.github/workflows/klipper3d-deploy.yaml b/.github/workflows/klipper3d-deploy.yaml
@@ -0,0 +1,29 @@
+name: klipper3d deploy
+on:
+  push:
+    branches:
+      - master
+    paths:
+      - docs/**
+      - mkdocs.yml
+      - .github/workflows/klipper3d-deploy.yaml
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Setup python
+        uses: actions/setup-python@v2
+        with:
+          python-version: '3.8'
+      - uses: actions/cache@v2
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ hashFiles('docs/_klipper3d/mkdocs-requirements.txt') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-
+      - name: Install dependencies
+        run: pip install -r docs/_klipper3d/mkdocs-requirements.txt
+      - name: Build and deploy klipper3d
+        run: |
+          mkdocs gh-deploy --force --remote-branch gh-pages --verbose
diff --git a/docs/API_Server.md b/docs/API_Server.md
@@ -1,9 +1,11 @@
+# API server
+
 This document describes Klipper's Application Programmer Interface
 (API). This interface enables external applications to query and
 control the Klipper host software.
 
 Enabling the API socket
-=======================
+-----------------------
 
 In order to use the API server, the klippy.py host software must be
 started with the `-a` parameter. For example:
@@ -16,7 +18,7 @@ can then open a connection on that socket and send commands to
 Klipper.
 
 Request format
-==============
+--------------
 
 Messages sent and received on the socket are JSON encoded strings
 terminated by an ASCII 0x03 character:
@@ -37,7 +39,7 @@ terminator when transmitting a request. (The Klipper API server does
 not have a newline requirement.)
 
 API Protocol
-============
+------------
 
 The command protocol used on the communication socket is inspired by
 [json-rpc](https://www.jsonrpc.org/).
@@ -91,7 +93,7 @@ respect to responses from other requests. A JSON request will never
 pause the processing of future JSON requests.
 
 Subscriptions
-=============
+-------------
 
 Some Klipper "endpoint" requests allow one to "subscribe" to future
 asynchronous update messages.
@@ -119,7 +121,7 @@ send that template. If a "response_template" field is not provided
 then it defaults to an empty dictionary (`{}`).
 
 Available "endpoints"
-=====================
+---------------------
 
 By convention, Klipper "endpoints" are of the form
 `<module_name>/<some_name>`. When making a request to an "endpoint",

diff --git a/docs/BLTouch.md b/docs/BLTouch.md
@@ -1,5 +1,7 @@
+# BL-Touch
+
 Connecting BL-Touch
-===================
+-------------------
 
 A **warning** before you start: Avoid touching the BL-Touch pin with
 your bare fingers, since it is quite sensitive to finger grease. And
@@ -38,7 +40,7 @@ that the probe doesn't hit anything even if the probe pin happens to
 be in its lowest state.
 
 Initial tests
-=============
+-------------
 
 Before moving on, verify that the BL-Touch is mounted at the correct
 height, the pin should be roughly 2 mm above the nozzle when retracted
@@ -82,7 +84,7 @@ If that was successful, do another `G28` (or `PROBE`) but this time
 let it touch the bed as it should.
 
 BL-Touch gone bad
-=================
+-----------------
 
 Once the BL-Touch is in inconsistent state, it starts blinking red.
 You can force it to leave that state by issuing:
@@ -105,7 +107,7 @@ light turns on and of. Use the `reset`, `pin_up` and `pin_down`
 commands to achieve this.
 
 BL-Touch "clones"
-=================
+-----------------
 
 Many BL-Touch "clone" devices work correctly with Klipper using the
 default configuration. However, some "clone" devices may require
@@ -143,7 +145,7 @@ the second query reports "probe: TRIGGERED" then it indicates that
 config file.
 
 BL-Touch v3
-===========
+-----------
 
 Some BL-Touch v3.0 and BL-Touch 3.1 devices may require configuring
 `probe_with_touch_mode` in the printer config file.
@@ -171,7 +173,7 @@ device, be sure to test the probe accuracy before and after setting
 this value (use the `PROBE_ACCURACY` command to test).
 
 Multi-probing without stowing
-=============================
+-----------------------------
 
 By default, Klipper will deploy the probe at the start of each probe
 attempt and then stow the probe afterwards. This repetitive deploying
@@ -202,7 +204,7 @@ before and after setting `probe_with_touch_mode` (use the
 `PROBE_ACCURACY` command to test).
 
 Calibrating the BL-Touch offsets
-================================
+--------------------------------
 
 Follow the directions in the [Probe Calibrate](Probe_Calibrate.md)
 guide to set the x_offset, y_offset, and z_offset config parameters.
@@ -217,7 +219,7 @@ If an adjustment is made to the probe position, then rerun the probe
 calibration steps.
 
 BL-Touch output mode
-====================
+--------------------
 
 * A BL-Touch V3.0 supports setting a 5V or OPEN-DRAIN output mode,
   a BL-Touch V3.1 supports this too, but can also store this in its

diff --git a/docs/Bed_Level.md b/docs/Bed_Level.md
@@ -1,3 +1,5 @@
+# Bed leveling
+
 Bed leveling (sometimes also referred to as "bed tramming") is
 critical to getting high quality prints. If a bed is not properly
 "leveled" it can lead to poor bed adhesion, "warping", and subtle
@@ -20,7 +22,7 @@ The secret to getting high accuracy is to use a repeatable process and
 to use a leveling method that leverages the high accuracy of the
 printer's own motion system.
 
-# Choose the appropriate calibration mechanism
+## Choose the appropriate calibration mechanism
 
 Different types of printers use different methods for performing bed
 leveling. All of them ultimately depend on the "paper test" (described
@@ -46,7 +48,7 @@ routines. Setting a negative number allows the printer to move below
 the nominal position of the bed, which may help when trying to
 determine the actual bed position.
 
-# The "paper test"
+## The "paper test"
 
 The primary bed calibration mechanism is the "paper test". It involves
 placing a regular piece of "copy machine paper" between the printer's
@@ -174,7 +176,7 @@ to obtain the same amount of friction each time one runs the test.
 If something goes wrong during the test, one can use the `ABORT`
 command to exit the calibration tool.
 
-# Determining Thermal Expansion
+## Determining Thermal Expansion
 
 After successfully performing bed leveling, one may go on to calculate
 a more precise value for the combined impact of "thermal expansion",

diff --git a/docs/Bed_Mesh.md b/docs/Bed_Mesh.md
@@ -1,3 +1,5 @@
+# Bed Mesh
+
 The Bed Mesh module may be used to compensate for bed surface irregularties to
 achieve a better first layer across the entire bed.  It should be noted that
 software based correction will not achieve perfect results, it can only

diff --git a/docs/Benchmarks.md b/docs/Benchmarks.md
@@ -1,7 +1,9 @@
+# Benchmarks
+
 This document describes Klipper benchmarks.
 
 Micro-controller Benchmarks
-===========================
+---------------------------
 
 This section describes the mechanism used to generate the Klipper
 micro-controller step rate benchmarks.
@@ -23,7 +25,7 @@ or other innocuous pins. **Always verify that it is safe to drive the
 configured pins prior to running a benchmark.** It is not recommended
 to drive an actual stepper during a benchmark.
 
-## Step rate benchmark test ##
+### Step rate benchmark test ###
 
 The test is performed using the console.py tool (described in
 [Debugging.md](Debugging.md)). The micro-controller is configured for
@@ -449,7 +451,7 @@ hub.
 | rp2040 (USB)        | 873K | c5667193 | arm-none-eabi-gcc (Fedora 10.2.0-4.fc34) 10.2.0 |
 
 Host Benchmarks
-===============
+---------------
 
 It is possible to run timing tests on the host software using the
 "batch mode" processing mechanism (described in

diff --git a/docs/Bootloaders.md b/docs/Bootloaders.md
@@ -1,3 +1,5 @@
+# Bootloaders
+
 This document provides information on common bootloaders found on
 micro-controllers that Klipper supports.
 
@@ -23,8 +25,8 @@ application.  This document is not an authoritative reference; it is
 intended as a collection of useful information that the Klipper
 developers have accumulated.
 
-AVR micro-controllers
-=====================
+## AVR micro-controllers ##
+
 
 In general, the Arduino project is a good reference for bootloaders
 and flashing procedures on the 8-bit Atmel Atmega micro-controllers.
@@ -44,7 +46,7 @@ use.
 The "avrdude" program is the most common tool used to flash atmega
 chips (both bootloader flashing and application flashing).
 
-## Atmega2560 ##
+### Atmega2560 ###
 
 This chip is typically found in the "Arduino Mega" and is very common
 in 3d printer boards.
@@ -63,7 +65,7 @@ To flash an application use something like:
 avrdude -cwiring -patmega2560 -P/dev/ttyACM0 -b115200 -D -Uflash:w:out/klipper.elf.hex:i
 ```
 
-## Atmega1280 ##
+### Atmega1280 ###
 
 This chip is typically found in earlier versions of the "Arduino
 Mega".
@@ -82,7 +84,7 @@ To flash an application use something like:
 avrdude -carduino -patmega1280 -P/dev/ttyACM0 -b57600 -D -Uflash:w:out/klipper.elf.hex:i
 ```
 
-## Atmega1284p ##
+### Atmega1284p ###
 
 This chip is commonly found in "Melzi" style 3d printer boards.
 
@@ -107,7 +109,7 @@ application use something like this instead:
 avrdude -carduino -patmega1284p -P/dev/ttyACM0 -b57600 -D -Uflash:w:out/klipper.elf.hex:i
 ```
 
-## At90usb1286 ##
+### At90usb1286 ###
 
 This document does not cover the method to flash a bootloader to the
 At90usb1286 nor does it cover general application flashing to this
@@ -122,7 +124,7 @@ One can flash an application with it using something like:
 teensy_loader_cli --mcu=at90usb1286 out/klipper.elf.hex -v
 ```
 
-## Atmega168 ##
+### Atmega168 ###
 
 The atmega168 has limited flash space. If using a bootloader, it is
 recommended to use the Optiboot bootloader. To flash that bootloader
@@ -142,7 +144,7 @@ avrdude -carduino -patmega168 -P/dev/ttyACM0 -b115200 -D -Uflash:w:out/klipper.e
 ```
 
 SAM3 micro-controllers (Arduino Due)
-====================================
+------------------------------------
 
 It is not common to use a bootloader with the SAM3 mcu. The chip
 itself has a ROM that allows the flash to be programmed from 3.3V
@@ -166,7 +168,7 @@ bossac -U -p /dev/ttyACM0 -R
 ```
 
 SAM4 micro-controllers (Duet Wifi)
-====================================
+----------------------------------
 
 It is not common to use a bootloader with the SAM4 mcu. The chip
 itself has a ROM that allows the flash to be programmed from 3.3V
@@ -186,7 +188,7 @@ bossac --port=/dev/ttyACM0 -b -U -e -w -v -R out/klipper.bin
 ```
 
 SAMD21 micro-controllers (Arduino Zero)
-=======================================
+---------------------------------------
 
 The SAMD21 bootloader is flashed via the ARM Serial Wire Debug (SWD)
 interface. This is commonly done with a dedicated SWD hardware dongle.
@@ -225,7 +227,7 @@ avrdude -c stk500v2 -p atmega2560 -P /dev/ttyACM0 -u -Uflash:w:out/klipper.elf.h
 ```
 
 SAMD51 micro-controllers (Adafruit Metro-M4 and similar)
-========================================================
+--------------------------------------------------------
 
 Like the SAMD21, the SAMD51 bootloader is flashed via the ARM Serial
 Wire Debug (SWD) interface. To flash a bootloader with
@@ -254,7 +256,7 @@ bossac -U -p /dev/ttyACM0 --offset=0x4000 -w out/klipper.bin -v -b -R
 ```
 
 STM32F103 micro-controllers (Blue Pill devices)
-===============================================
+-----------------------------------------------
 
 The STM32F103 devices have a ROM that can flash a bootloader or
 application via 3.3V serial. To access this ROM, one should connect
@@ -274,7 +276,7 @@ for details on enabling the full uart on the Raspberry Pi GPIO pins.
 After flashing, set both "boot 0" and "boot 1" back to low so that
 future resets boot from flash.
 
-## STM32F103 with stm32duino bootloader ##
+### STM32F103 with stm32duino bootloader ###
 
 The "stm32duino" project has a USB capable bootloader - see:
 [https://github.com/rogerclarkmelbourne/STM32duino-bootloader](https://github.com/rogerclarkmelbourne/STM32duino-bootloader)
@@ -299,7 +301,7 @@ bootloader is still active (the bootloader will flash a board led
 while it is running). Alternatively, set the "boot 0" pin to low and
 "boot 1" pin to high to stay in the bootloader after a reset.
 
-## STM32F103 with HID bootloader ##
+### STM32F103 with HID bootloader ###
 The [HID bootloader](https://github.com/Serasidis/STM32_HID_Bootloader) is a
 compact, driverless bootloader capable of flashing over USB. Also available
 is a [fork with builds specific to the SKR Mini E3 1.2](
@@ -422,7 +424,7 @@ programming is complete unplug the device and set "boot 1" back to low
 so the application will be loaded.
 
 LPC176x micro-controllers (Smoothieboards)
-==========================================
+------------------------------------------
 
 This document does not describe the method to flash a bootloader
 itself - see:
@@ -438,7 +440,7 @@ this bootloader is to copy the application file (eg,
 then to reboot the micro-controller with that SD card.
 
 Running OpenOCD on the Raspberry PI
-===================================
+-----------------------------------
 
 OpenOCD is a software package that can perform low-level chip flashing
 and debugging. It can use the GPIO pins on a Raspberry Pi to
@@ -464,7 +466,7 @@ make
 make install
 ```
 
-## Configure OpenOCD
+### Configure OpenOCD
 
 Create an OpenOCD config file:
 
@@ -498,7 +500,7 @@ targets
 reset halt
 ```
 
-## Wire the Raspberry Pi to the target chip
+### Wire the Raspberry Pi to the target chip
 
 Poweroff both the the Raspberry Pi and the target chip before wiring!
 Verify the target chip uses 3.3V prior to connecting to a Raspberry
@@ -509,7 +511,7 @@ GPIO24, and GPIO18 respectively on the Raspberry Pi.
 
 Then power up the Raspberry Pi and provide power to the target chip.
 
-## Run OpenOCD
+### Run OpenOCD
 
 Run OpenOCD:
 
@@ -533,7 +535,7 @@ telnet 127.0.0.1 4444
 (One can exit telnet by pressing ctrl+] and then running the "quit"
 command.)
 
-## OpenOCD and gdb
+### OpenOCD and gdb
 
 It is possible to use OpenOCD with gdb to debug Klipper. The following
 commands assume one is running gdb on a desktop class machine.