Implement autogeneration of Documentation/README.md (#1738)

* mkdocs.yml: unify formatting style

* Docs/README.md: add auto-generated README.md file for Documentation/ directory

* Docs/README.md: fix refs

* Docs/README.md: fix locations

* Docs/README.md: trying workaround spaces in filenames for refs

* Documentation/README.md: update generated file trying to fix all formatting issues

* Documentation/README.md: reduce title size

* Documentation/README.md: add link for official online docs

* scripts/deploy.sh: implement docs_readme function

* deploy.sh: add overwrite warning in help output

* deploy.sh: try to fix shellcheck warnings

* deploy.sh:docs_readme() - show note message only if README should be updated

* deploy.sh:docs_readme() - fix shellcheck

* github/push: add Documentation/README.md check

* github/push: force usage of /bin/sh for deploy.sh script

* testing, testing, testing

* deploy.sh:docs_readme() - make error-related message more clear about what to donext

* Revert change used only to test failure on github CI

.github/workflows/push.yml

@@ -140,7 +140,7 @@ jobs:
 
     steps:
       - name: deps
-        run: apk add --no-cache python3 py3-pip make git black
+        run: apk add --no-cache python3 py3-pip make git black sed diffutils
 
       - uses: actions/checkout@v3
         with:
@@ -158,6 +158,9 @@ jobs:
       - name: Check python with flake8
         run: flake8 Translations
 
+      - name: Check autogenerated Documentation/README.md
+        run: /bin/sh ./scripts/deploy.sh docs_readme
+
   shellcheck:
     name: runner / shellcheck
     runs-on: ubuntu-latest

Documentation/README.md

@@ -0,0 +1,29 @@
+
+<!-- THIS FILE IS AUTOGENERATED by "scripts/deploy.sh docs_readme" based on nav section in scripts/IronOS-mkdocs.yml config -->
+<!-- THIS FILE IS NOT SUPPOSED TO BE EDITED MANUALLY -->
+
+#### This is autogenerated README for brief navigation through github over official documentation for IronOS project
+#### This documentation is also available [here online](https://ralim.github.io/IronOS)
+
+  - [Home](../Documentation/index.md)
+  - [Getting Started](../Documentation/GettingStarted.md)
+  - Flashing the firmware
+      - [MHP30](../Documentation/Flashing/MHP30.md)
+      - [Pinecil V1](../Documentation/Flashing/Pinecil%20V1.md)
+      - [Pinecil V2](../Documentation/Flashing/Pinecil%20V2.md)
+      - [TS80(P)](../Documentation/Flashing/TS80(P).md)
+      - [TS100](../Documentation/Flashing/TS100.md)
+  - Operation
+      - [Main Menu](../Documentation/Menu.md)
+      - [Settings](../Documentation/Settings.md)
+      - [Debug Menu](../Documentation/DebugMenu.md)
+      - [Power](../Documentation/Power.md)
+      - [Temperature](../Documentation/Temperature.md)
+  - [Startup Logo](../Documentation/Logo.md)
+  - Hardware
+      - [Hall Sensor (Pinecil)](../Documentation/HallSensor.md)
+      - [Hardware Notes](../Documentation/Hardware.md)
+      - [Troubleshooting](../Documentation/Troubleshooting.md)
+      - [Known Hardware Issues](../Documentation/HardwareIssues.md)
+  - [Translations](../Documentation/Translation.md)
+  - [Development](../Documentation/Development.md)

scripts/IronOS-mkdocs.yml

@@ -3,9 +3,10 @@ site_name: IronOS
 site_url: https://ralim.github.io/IronOS/
 site_description: "IronOS Open Source Soldering Iron firmware for Miniware and Pinecil"
 
-# repo config
+# Repo config
 repo_url: https://github.com/ralim/IronOS/
 
+# Dir & location config
 docs_dir: ../Documentation
 edit_uri: edit/dev/Documentation/
 
@@ -16,6 +17,7 @@ theme:
     hljs_languages:
         - yaml
 
+# Navigation structure
 nav:
   - Home: index.md
   - Getting Started: GettingStarted.md
@@ -47,7 +49,6 @@ plugins:
   - awesome-pages
   - git-revision-date
 
-
 # Markdown Extensions
 markdown_extensions:
   - attr_list

scripts/deploy.sh

@@ -3,20 +3,70 @@
 # little helper for docker deployment to:
 # - start development environment for IronOS ("shell" sub-command)
 # - generate full set of builds ("build" sub-command)
+# - probably doing some other routines (check source briefly before running undocumented commands!)
 
 #set -x
 #set -e
 
+### helper functions
+
 usage()
 {
 	echo -e "\nUsage: ${0} [CMD]\n"
-	echo "CMD:"
+	echo "CMD (docker related):"
 	echo -e "\tshell - start docker container with shell inside to work on IronOS with all tools needed"
 	echo -e "\tbuild - compile builds of IronOS inside docker container for supported hardware"
 	echo -e "\tclean - delete created docker container (but not pre-downloaded data for it)\n"
+	echo "CMD (helper routines):"
+	echo -e "\tdocs_readme - generate & OVERWRITE(!) README.md inside Documentation/ based on nav section from mkdocs.yml if it changed\n"
 	echo -e "STORAGE NOTICE: for \"shell\" and \"build\" commands extra files will be downloaded so make sure that you have ~5GB of free space.\n"
 }
 
+docs_readme()
+{
+	# WARNING: ON RUN Documentaion/README.md MAY BE OVERWRITTEN WITHOUT ANY WARNINGS / CONFIRMATIONS !!!
+	# Returns:
+	## 0 to the environment & silence - if there are no any changes in README.md nor updates in mkdocs.yml
+	## 1 to the environment (as error) & note message - if the update of README.md in repo is required
+	yml="scripts/IronOS-mkdocs.yml"
+	md_old="Documentation/README.md"
+	md_new="Documentation/README"
+	# ^^^^ hardcoded paths relative to IronOS/ to make this func very trivial
+# file overwritten section looks out of style but hoping to make shellcheck happy
+cat << EOF > "${md_new}"
+
+<!-- THIS FILE IS AUTOGENERATED by "scripts/deploy.sh docs_readme" based on nav section in ${yml} config -->
+<!-- THIS FILE IS NOT SUPPOSED TO BE EDITED MANUALLY -->
+
+#### This is autogenerated README for brief navigation through github over official documentation for IronOS project
+#### This documentation is also available [here online](https://ralim.github.io/IronOS)
+
+EOF
+	# it probably will become unexplainable in a few months but so far it works:
+	sed '1,/^nav/d; /^ *$/,$d; s,- ,- [,; s,: ,](../Documentation/,; s,.md,.md),; s,:$,],; s,/Pinecil ,/Pinecil%20,; /^  - \[.*\]$/ s,\[,,; s,]$,,' "${yml}" >> "${md_new}"
+	ret=0
+	if [ -z "$(diff -q "${md_old}" "${md_new}")" ]; then
+		rm "${md_new}"
+		ret=0
+	else
+		mv "${md_new}" "${md_old}"
+		echo ""
+		echo "${yml} seems to be updated..."
+		echo "... while ${md_old} is out-of-date!"
+		echo ""
+		echo "Please, update ${md_old} in your local working copy by command:"
+		echo ""
+		echo " $ ./scripts/deploy.sh docs_readme"
+		echo ""
+		echo "And then commit & push changes to update ${md_old} in the repo:"
+		echo ""
+		echo " $ git commit ${md_old} -m \"${md_old}: update autogenerated file\" && git push"
+		echo ""
+		ret=1
+	fi;
+	return "${ret}"
+}
+
 ### main
 
 docker_conf="Env.yml"
@@ -42,6 +92,19 @@ if [ -n "${docker_tool}" ] && [ -z "${docker_bin}" ]; then
 	docker_bin="${docker_tool}  compose"
 fi;
 
+# give function argument a name
+
+cmd="${1}"
+
+# if only README.md for Documentation update is required then run it & exit
+
+if [ "docs_readme" = "${cmd}" ]; then
+	docs_readme
+	exit "${?}"
+fi;
+
+# if docker is not presented in any way show warning & exit
+
 if [ -z "${docker_bin}" ]; then
 	echo "ERROR: Can't find docker-compose nor docker tool. Please, install docker and try again."
 	exit 1
@@ -49,7 +112,6 @@ fi;
 
 # construct command to run
 
-cmd="${1}"
 if [ -z "${cmd}" ] || [ "${cmd}" = "shell" ]; then
 	docker_cmd="run  --rm  builder"
 elif [ "${cmd}" = "build" ]; then