Docs: rework to Kalico (#459)

* docs overhaul (kalico)

* rename references of branch `master` to `main`

* add migration page

* fix punctuation

* remove releases page

* fix repo_name

* update logos

* rename to Kalico in Readme

* update discord banner

* fix discord url in readme

* docs: fix refs

---------

Co-authored-by: Rogerio Goncalves <[email protected]>

.github/workflows/klipper3d-deploy.yaml → .github/workflows/cd-docs.yaml

@@ -1,12 +1,12 @@
-name: klipper3d deploy
+name: docs deployment
 on:
   workflow_dispatch:
   push:
     branches:
       - master
     paths:
       - docs/**
-      - .github/workflows/klipper3d-deploy.yaml
+      - .github/workflows/cd-docs.yaml
 
 jobs:
   deploy:
@@ -20,17 +20,21 @@ jobs:
           python-version: "3.10"
 
       - uses: actions/cache@v3
+        id: pip-cache
         with:
           path: ~/.cache/pip
-          key: ${{ runner.os }}-pip-${{ hashFiles('docs/_klipper3d/mkdocs-requirements.txt') }}
+          key: ${{ runner.os }}-pip-${{ hashFiles('docs/_kalico/mkdocs-requirements.txt') }}
           restore-keys: |
             ${{ runner.os }}-pip-
 
       - name: Install dependencies
-        run: pip install -r docs/_klipper3d/mkdocs-requirements.txt
+        if: steps.pip-cache.outputs.cache-hit != 'true'
+        run: pip install -r docs/_kalico/mkdocs-requirements.txt
 
       - name: Build MkDocs Pages
-        run: docs/_klipper3d/build-translations.sh
+        run: |
+          cd docs/
+          mkdocs build -f _kalico/mkdocs.yml
 
       - name: Deploy
         uses: JamesIves/[email protected]

.github/workflows/ci-docs_test.yaml

@@ -0,0 +1,34 @@
+name: docs deployment
+on:
+  pull_request:
+    paths:
+      - docs/**
+      - .github/workflows/ci-docs_test.yaml
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.10"
+
+      - uses: actions/cache@v3
+        id: pip-cache
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ hashFiles('docs/_kalico/mkdocs-requirements.txt') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-
+
+      - name: Install dependencies
+        if: steps.pip-cache.outputs.cache-hit != 'true'
+        run: pip install -r docs/_kalico/mkdocs-requirements.txt
+
+      - name: Build MkDocs Pages
+        run: |
+          cd docs/
+          mkdocs build -f _kalico/mkdocs.yml --strict

.gitignore

@@ -1,6 +1,8 @@
+# development
 out
 *.so
 *.pyc
+__pycache__/
 .config
 .config.old
 klippy/.version
@@ -12,3 +14,11 @@ _test_.*
 klippy/plugins/*
 !klippy/plugins/__init__.py
 .vscode
+
+# docs
+site/
+.env/
+.venv/
+env/
+venv/
+mkdocs-env/

docs/API_Server.md

@@ -1,8 +1,8 @@
 # API server
 
-This document describes Klipper's Application Programmer Interface
+This document describes Kalico's Application Programmer Interface
 (API). This interface enables external applications to query and
-control the Klipper host software.
+control the Kalico host software.
 
 ## Enabling the API socket
 
@@ -14,10 +14,10 @@ started with the `-a` parameter. For example:
 
 This causes the host software to create a Unix Domain Socket. A client
 can then open a connection on that socket and send commands to
-Klipper.
+Kalico.
 
 See the [Moonraker](https://github.com/Arksine/moonraker) project for
-a popular tool that can forward HTTP requests to Klipper's API Server
+a popular tool that can forward HTTP requests to Kalico's API Server
 Unix Domain Socket.
 
 ## Request format
@@ -28,16 +28,16 @@ terminated by an ASCII 0x03 character:
 <json_object_1><0x03><json_object_2><0x03>...
 ```
 
-Klipper contains a `scripts/whconsole.py` tool that can perform the
+Kalico contains a `scripts/whconsole.py` tool that can perform the
 above message framing. For example:
 ```
 ~/klipper/scripts/whconsole.py /tmp/klippy_uds
 ```
 
 This tool can read a series of JSON commands from stdin, send them to
-Klipper, and report the results. The tool expects each JSON command to
+Kalico, and report the results. The tool expects each JSON command to
 be on a single line, and it will automatically append the 0x03
-terminator when transmitting a request. (The Klipper API server does
+terminator when transmitting a request. (The Kalico API server does
 not have a newline requirement.)
 
 ## API Protocol
@@ -63,17 +63,17 @@ term "dictionary" to describe a "JSON object" - a mapping of key/value
 pairs contained within `{}`.)
 
 The request dictionary must contain a "method" parameter that is the
-string name of an available Klipper "endpoint".
+string name of an available Kalico "endpoint".
 
 The request dictionary may contain a "params" parameter which must be
 of a dictionary type. The "params" provide additional parameter
-information to the Klipper "endpoint" handling the request. Its
+information to the Kalico "endpoint" handling the request. Its
 content is specific to the "endpoint".
 
 The request dictionary may contain an "id" parameter which may be of
-any JSON type. If "id" is present then Klipper will respond to the
+any JSON type. If "id" is present then Kalico will respond to the
 request with a response message containing that "id". If "id" is
-omitted (or set to a JSON "null" value) then Klipper will not provide
+omitted (or set to a JSON "null" value) then Kalico will not provide
 any response to the request. A response message is a JSON dictionary
 containing "id" and "result". The "result" is always a dictionary -
 its contents are specific to the "endpoint" handling the request.
@@ -87,15 +87,15 @@ might result in an error response such as:
 `{"id": 123, "error": {"message": "Must home axis
 first: 200.000 0.000 0.000 [0.000]", "error": "WebRequestError"}}`
 
-Klipper will always start processing requests in the order that they
+Kalico will always start processing requests in the order that they
 are received. However, some request may not complete immediately,
 which could cause the associated response to be sent out of order with
 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
+Some Kalico "endpoint" requests allow one to "subscribe" to future
 asynchronous update messages.
 
 For example:
@@ -107,50 +107,50 @@ may initially respond with:
 
 `{"id": 123, "result": {}}`
 
-and cause Klipper to send future messages similar to:
+and cause Kalico to send future messages similar to:
 
 `{"params": {"response": "ok B:22.8 /0.0 T0:22.4 /0.0"}, "key": 345}`
 
 A subscription request accepts a "response_template" dictionary in the
 "params" field of the request. That "response_template" dictionary is
 used as a template for future asynchronous messages - it may contain
 arbitrary key/value pairs. When sending these future asynchronous
-messages, Klipper will add a "params" field containing a dictionary
+messages, Kalico will add a "params" field containing a dictionary
 with "endpoint" specific contents to the response template and then
 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
+By convention, Kalico "endpoints" are of the form
 `<module_name>/<some_name>`. When making a request to an "endpoint",
 the full name must be set in the "method" parameter of the request
 dictionary (eg, `{"method"="gcode/restart"}`).
 
 ### info
 
 The "info" endpoint is used to obtain system and version information
-from Klipper. It is also used to provide the client's version
-information to Klipper. For example:
+from Kalico. It is also used to provide the client's version
+information to Kalico. For example:
 `{"id": 123, "method": "info", "params": { "client_info": { "version":
 "v1"}}}`
 
 If present, the "client_info" parameter must be a dictionary, but that
 dictionary may have arbitrary contents. Clients are encouraged to
 provide the name of the client and its software version when first
-connecting to the Klipper API server.
+connecting to the Kalico API server.
 
 ### emergency_stop
 
-The "emergency_stop" endpoint is used to instruct Klipper to
+The "emergency_stop" endpoint is used to instruct Kalico to
 transition to a "shutdown" state. It behaves similarly to the G-Code
 `M112` command. For example:
 `{"id": 123, "method": "emergency_stop"}`
 
 ### register_remote_method
 
 This endpoint allows clients to register methods that can be called
-from klipper.  It will return an empty object upon success.
+from Kalico.  It will return an empty object upon success.
 
 For example:
 `{"id": 123, "method": "register_remote_method",
@@ -159,7 +159,7 @@ For example:
 will return:
 `{"id": 123, "result": {}}`
 
-The remote method `paneldue_beep` may now be called from Klipper. Note
+The remote method `paneldue_beep` may now be called from KliKalicopper. Note
 that if the method takes parameters they should be provided as keyword
 arguments. Below is an example of how it may called from a gcode_macro:
 ```
@@ -168,7 +168,7 @@ gcode:
   {action_call_remote_method("paneldue_beep", frequency=300, duration=1.0)}
 ```
 
-When the PANELDUE_BEEP gcode macro is executed, Klipper would send something
+When the PANELDUE_BEEP gcode macro is executed, Kalico would send something
 like the following over the socket:
 `{"action": "run_paneldue_beep",
 "params": {"frequency": 300, "duration": 1.0}}`
@@ -271,7 +271,7 @@ after any pending G-Code commands complete.
 ### gcode/subscribe_output
 
 This endpoint is used to subscribe to G-Code terminal messages that
-are generated by Klipper. For example:
+are generated by Kalico. For example:
 `{"id": 123, "method": "gcode/subscribe_output", "params":
 {"response_template":{}}}`
 might later produce asynchronous messages such as:
@@ -280,14 +280,14 @@ might later produce asynchronous messages such as:
 This endpoint is intended to support human interaction via a "terminal
 window" interface. Parsing content from the G-Code terminal output is
 discouraged. Use the "objects/subscribe" endpoint to obtain updates on
-Klipper's state.
+Kalico's state.
 
 ### motion_report/dump_stepper
 
-This endpoint is used to subscribe to Klipper's internal stepper
+This endpoint is used to subscribe to Kalico's internal stepper
 queue_step command stream for a stepper. Obtaining these low-level
 motion updates may be useful for diagnostic and debugging
-purposes. Using this endpoint may increase Klipper's system load.
+purposes. Using this endpoint may increase Kalico's system load.
 
 A request may look like:
 `{"id": 123, "method":"motion_report/dump_stepper",
@@ -306,10 +306,10 @@ the fields found in later "data" responses.
 
 ### motion_report/dump_trapq
 
-This endpoint is used to subscribe to Klipper's internal "trapezoid
+This endpoint is used to subscribe to Kalico's internal "trapezoid
 motion queue". Obtaining these low-level motion updates may be useful
 for diagnostic and debugging purposes. Using this endpoint may
-increase Klipper's system load.
+increase Kalico's system load.
 
 A request may look like:
 `{"id": 123, "method": "motion_report/dump_trapq", "params":
@@ -329,7 +329,7 @@ the fields found in later "data" responses.
 
 This endpoint is used to subscribe to ADXL345 accelerometer data.
 Obtaining these low-level motion updates may be useful for diagnostic
-and debugging purposes. Using this endpoint may increase Klipper's
+and debugging purposes. Using this endpoint may increase Kalico's
 system load.
 
 A request may look like:
@@ -350,7 +350,7 @@ the fields found in later "data" responses.
 This endpoint is used to subscribe to
 [angle sensor data](Config_Reference.md#angle). Obtaining these
 low-level motion updates may be useful for diagnostic and debugging
-purposes. Using this endpoint may increase Klipper's system load.
+purposes. Using this endpoint may increase Kalico's system load.
 
 A request may look like:
 `{"id": 123, "method":"angle/dump_angle",
@@ -368,7 +368,7 @@ the fields found in later "data" responses.
 
 This endpoint is used to subscribe to raw HX711 and HX717 ADC data.
 Obtaining these low-level ADC updates may be useful for diagnostic
-and debugging purposes. Using this endpoint may increase Klipper's
+and debugging purposes. Using this endpoint may increase Kalico's
 system load.
 
 A request may look like:
@@ -384,7 +384,7 @@ and might later produce asynchronous messages such as:
 
 This endpoint is used to subscribe to raw ADS1220 ADC data.
 Obtaining these low-level ADC updates may be useful for diagnostic
-and debugging purposes. Using this endpoint may increase Klipper's
+and debugging purposes. Using this endpoint may increase Kalico's
 system load.
 
 A request may look like:

docs/Axis_Twist_Compensation.md

@@ -35,8 +35,7 @@ points along the bed
 [Screws Tilt Adjust](G-Codes.md#screws_tilt_adjust),
 [Z Tilt Adjust](G-Codes.md#z_tilt_adjust) etc
 4. Home all axis, then perform a [Bed Mesh](Bed_Mesh.md) if required
-5. Perform a test print, followed by any
-[fine-tuning](Axis_Twist_Compensation.md#fine-tuning) as desired
+5. Perform a test print, followed by any fine-tuning as desired
 
 > **Tip:** Bed temperature and nozzle temperature and size do not seem to have
 > an influence to the calibration process.