Deploying to gh-pages from @ Klipper3d/klipper@61792e3e31 🚀

_klipper3d/README

@@ -0,0 +1,20 @@
+This directory defines the https://www.klipper3d.org/ website. The
+site is hosted using "github pages". The
+.github/workflows/klipper3d-deploy.yaml tool uses mkdocs (
+https://www.mkdocs.org/ ) to automatically convert the markdown files
+in the docs/ directory to html. In addition to the files in this
+directory, the docs/CNAME file also controls the website generation.
+
+To test deploy the main English site locally one can use commands
+similar to the following:
+
+virtualenv ~/mkdocs-env && ~/python-env/bin/pip install -r ~/klipper/docs/_klipper3d/mkdocs-requirements.txt
+cd ~/klipper && ~/mkdocs-env/bin/mkdocs serve --config-file ~/klipper/docs/_klipper3d/mkdocs.yml -a 0.0.0.0:8000
+
+To test deploy the multi-language site locally one can use commands
+similar to the following:
+
+virtualenv ~/mkdocs-env && ~/python-env/bin/pip install -r ~/klipper/docs/_klipper3d/mkdocs-requirements.txt
+source ~/mkdocs-env/bin/activate
+cd ~/klipper && ./docs/_klipper3d/build-translations.sh
+cd ~/klipper/site/ && python3 -m http.server 8000

_klipper3d/build-translations.sh

@@ -0,0 +1,64 @@
+#!/bin/bash
+# This script extracts the Klipper translations and builds multiple
+# mdocs sites - one for each supported language.  See the README file
+# for additional details.
+
+MKDOCS_DIR="docs/_klipper3d/"
+WORK_DIR="work/"
+TRANS_DIR="${WORK_DIR}klipper-translations/"
+TRANS_FILE="${TRANS_DIR}active_translations"
+MKDOCS_MAIN="${MKDOCS_DIR}mkdocs-main.yml"
+
+# Fetch translations
+git clone --depth 1 https://github.com/Klipper3d/klipper-translations ${TRANS_DIR}
+
+# Create new mkdocs-main.yml with language links
+cp ${MKDOCS_DIR}mkdocs.yml ${MKDOCS_MAIN}
+while IFS="," read dirname langsite langdesc langsearch; do
+  sed -i "s%^.*# Alternate language links automatically added here$%    - name: ${langdesc}\n      link: /${langsite}/\n      lang: ${langsite}\n\0%" ${MKDOCS_MAIN}
+done < <(egrep -v '^ *(#|$)' ${TRANS_FILE})
+
+# Build main English website
+echo "building site for en"
+mkdocs build -f ${MKDOCS_MAIN}
+
+# Build each additional language website
+while IFS="," read dirname langsite langdesc langsearch; do
+  new_docs_dir="${WORK_DIR}lang/${langsite}/docs/"
+  locale_dir="${TRANS_DIR}/docs/locales/${dirname}"
+
+  # Copy markdown files to new_docs_dir
+  echo "Copying $dirname to $langsite"
+  mkdir -p "${new_docs_dir}"
+  cp "${locale_dir}"/*.md "${new_docs_dir}"
+  echo "copy resources"
+  cp -r docs/img "${new_docs_dir}"
+  cp -r docs/prints "${new_docs_dir}"
+  cp -r docs/_klipper3d "${new_docs_dir}"
+
+  # manually replace index.md if a manual-index.md exist
+  manual_index="${new_docs_dir}manual-index.md"
+  if [[ -f "${manual_index}" ]]; then
+    mv -f "${manual_index}" "${new_docs_dir}index.md"
+    echo "replaced index.md with manual_index.md for $langsite"
+  else
+    echo "Manually translated index file for $langsite not found!"
+  fi
+
+  # Create language specific mkdocs-lang-xxx.yml file
+  echo "create language specific mkdocs configurations for ${langsite}"
+  new_mkdocs_file="${new_docs_dir}_klipper3d/mkdocs-lang-${langsite}.yml"
+  cp "${MKDOCS_MAIN}" "${new_mkdocs_file}"
+
+  echo "replace search language"
+  sed -i "s%^    lang: en$%    lang: ${langsearch}%" "${new_mkdocs_file}"
+
+  echo "replace site language"
+  sed -i "s%^  language: en$%  language: ${langsite}%" "${new_mkdocs_file}"
+
+  # Build site
+  echo "building site for ${langsite}"
+  mkdir -p "${PWD}/site/${langsite}/"
+  ln -sf "${PWD}/site/${langsite}/" "${WORK_DIR}lang/${langsite}/site"
+  mkdocs build -f "${new_mkdocs_file}"
+done < <(egrep -v '^ *(#|$)' ${TRANS_FILE})

_klipper3d/fetch-translations.sh

@@ -1,29 +0,0 @@
-#!/bin/bash
-# Modify the file structure before running mkdocs
-# This is a make shift script before the current structure of
-# Klipper-translations can be directly utilized by mkdocs
-
-git clone --depth 1 https://github.com/Klipper3d/klipper-translations
-
-while IFS="," read dirname langname langdesc note; do
-  # move and rename markdown files
-  local_dir="klipper-translations/docs/locales/$dirname"
-  echo "Moving $dirname to $langname"
-  for file in "$local_dir"/*.md; do
-    mdfilename="${file/$local_dir\//}"
-    mv "$file" "./docs/${mdfilename//.md/.${langname}.md}"
-  done
-
-  # manually replace index.md if a manual-index.md exist
-  manual_index="./docs/manual-index.$langname.md"
-
-  if [[ -f "$manual_index" ]];then
-    mv "$manual_index" "./docs/index.${langname}.md"
-    echo "replaced index.${langname}.md with $manual_index"
-  else
-      echo "Manually translated index file for $dirname not found!"
-  fi
-
-  # add to translations.yml
-  echo "      ${langname}: ${langdesc}" >> ./docs/_klipper3d/translations.yml
-done <  <(egrep -v '^ *(#|$)' ./klipper-translations/active_translations)

_klipper3d/index

@@ -1,6 +0,0 @@
-This directory defines the https://www.klipper3d.org/ website. The
-site is hosted using "github pages". The
-.github/workflows/klipper3d-deploy.yaml tool uses mkdocs (
-https://www.mkdocs.org/ ) to automatically convert the markdown files
-in the docs/ directory to html. In addition to the files in this
-directory, the docs/CNAME file also controls the website generation.

_klipper3d/mkdocs-main.yml

@@ -0,0 +1,142 @@
+# Main configuration file for mkdocs generation of klipper3d.org website
+
+# Note that the build-translations.sh script expects a certain file
+# layout.  See that script and the README file for more details.
+
+# Site and directory configuration
+site_name: Klipper documentation
+repo_url: https://github.com/Klipper3d/klipper
+repo_name: Klipper3d/klipper
+edit_uri: blob/master/docs/
+use_directory_urls: False
+docs_dir: '../'
+site_dir: '../../site/'
+
+# Custom markdown dialect settings
+markdown_extensions:
+  - toc:
+      permalink: True
+      toc_depth: 6
+  - attr_list
+  - mdx_partial_gfm
+  - mdx_truly_sane_lists
+  - mdx_breakless_lists
+plugins:
+  search:
+    lang: en
+  mkdocs-simple-hooks:
+    hooks:
+      on_page_markdown: "docs._klipper3d.mkdocs_hooks:transform"
+  exclude:
+    glob: "README.md"
+
+# Website layout configuration (using mkdocs-material theme)
+theme:
+  name: material
+  palette:
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: white
+      accent: blue
+      toggle:
+        icon: material/lightbulb
+        name: Switch to dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: grey
+      accent: light blue
+      toggle:
+        icon: material/lightbulb-outline
+        name: Switch to light mode
+  logo: img/klipper.svg
+  favicon: img/favicon.ico
+  icon:
+    repo: fontawesome/brands/github
+    alternate: material/web
+  features:
+      #- navigation.tabs
+      #- navigation.expand
+      - navigation.top
+      # if enabled, the TOC doesn't work for some pages
+      # - toc.integrate
+      - search.suggest
+      - search.highlight
+      - search.share
+  language: en
+extra_css:
+  - _klipper3d/css/extra.css
+
+# Site usage statistics
+extra:
+  # https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-analytics/#site-search-tracking
+  analytics:
+    provider: google
+    property: UA-138371409-1
+  # Language Selection
+  alternate:
+    - name: English
+      link: /
+      lang: en
+    - name: 简体中文
+      link: /zh/
+      lang: zh
+    - name: 繁體中文
+      link: /zh-Hant/
+      lang: zh-Hant
+    # Alternate language links automatically added here
+
+# Navigation hierarchy (this should mimic the layout of Overview.md)
+nav:
+  - Overview.md
+  - Features.md
+  - FAQ.md
+  - Releases.md
+  - Config_Changes.md
+  - Contact.md
+  - Installation and Configuration:
+    - Installation.md
+    - Configuration Reference:
+      - Config_Reference.md
+      - Rotation_Distance.md
+    - Config_checks.md
+    - Bed Level:
+      - Bed_Level.md
+      - Delta_Calibrate.md
+      - Probe_Calibrate.md
+      - BLTouch.md
+      - Manual_Level.md
+      - Bed_Mesh.md
+      - Endstop_Phase.md
+    - Resonance Compensation:
+      - Resonance_Compensation.md
+      - Measuring_Resonances.md
+    - Pressure_Advance.md
+    - G-Codes.md
+    - Command templates:
+      - Command_Templates.md
+      - Status_Reference.md
+    - TMC_Drivers.md
+    - Multi_MCU_Homing.md
+    - Slicers.md
+    - Skew_Correction.md
+    - Using_PWM_Tools.md
+  - Developer Documentation:
+    - Code_Overview.md
+    - Kinematics.md
+    - Protocol.md
+    - API_Server.md
+    - MCU_Commands.md
+    - CANBUS_protocol.md
+    - Debugging.md
+    - Benchmarks.md
+    - CONTRIBUTING.md
+    - Packaging.md
+  - Device Specific Documents:
+    - Example_Configs.md
+    - SDCard_Updates.md
+    - RPi_microcontroller.md
+    - Beaglebone.md
+    - Bootloaders.md
+    - CANBUS.md
+    - TSL1401CL_Filament_Width_Sensor.md
+    - Hall_Filament_Width_Sensor.md

_klipper3d/mkdocs-requirements.txt

@@ -7,4 +7,3 @@ mkdocs-exclude==1.0.2
 mdx-truly-sane-lists==1.2
 mdx-breakless-lists==1.0.1
 py-gfm==1.0.2
-mkdocs-static-i18n==0.30

_klipper3d/mkdocs.yml

@@ -1,5 +1,8 @@
 # Main configuration file for mkdocs generation of klipper3d.org website
 
+# Note that the build-translations.sh script expects a certain file
+# layout.  See that script and the README file for more details.
+
 # Site and directory configuration
 site_name: Klipper documentation
 repo_url: https://github.com/Klipper3d/klipper
@@ -8,9 +11,8 @@ edit_uri: blob/master/docs/
 use_directory_urls: False
 docs_dir: '../'
 site_dir: '../../site/'
-INHERIT: translations.yml
 
-# Markdown document translation settings
+# Custom markdown dialect settings
 markdown_extensions:
   - toc:
       permalink: True
@@ -20,7 +22,8 @@ markdown_extensions:
   - mdx_truly_sane_lists
   - mdx_breakless_lists
 plugins:
-  search: {}
+  search:
+    lang: en
   mkdocs-simple-hooks:
     hooks:
       on_page_markdown: "docs._klipper3d.mkdocs_hooks:transform"
@@ -59,6 +62,7 @@ theme:
       - search.suggest
       - search.highlight
       - search.share
+  language: en
 extra_css:
   - _klipper3d/css/extra.css
 
@@ -68,6 +72,12 @@ extra:
   analytics:
     provider: google
     property: UA-138371409-1
+  # Language Selection
+  alternate:
+    - name: English
+      link: /
+      lang: en
+    # Alternate language links automatically added here
 
 # Navigation hierarchy (this should mimic the layout of Overview.md)
 nav:

_klipper3d/translations.yml

@@ -1,7 +0,0 @@
-# Klipper3d.org language translation template file.
-# Actual language definitions are appended by the fetch-translations.sh script.
-plugins:
-  i18n:
-    default_language: en
-    languages:
-      en: English