diff --git a/.github/workflows/push.yml b/.github/workflows/push.yml index 765910f9..9f904a2a 100644 --- a/.github/workflows/push.yml +++ b/.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 diff --git a/Documentation/README.md b/Documentation/README.md new file mode 100644 index 00000000..87807298 --- /dev/null +++ b/Documentation/README.md @@ -0,0 +1,29 @@ + + + + +#### 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) diff --git a/scripts/IronOS-mkdocs.yml b/scripts/IronOS-mkdocs.yml index 9514aa1b..24515f68 100644 --- a/scripts/IronOS-mkdocs.yml +++ b/scripts/IronOS-mkdocs.yml @@ -3,19 +3,21 @@ 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/ # Theme and config -theme: +theme: name: readthedocs highlightsjs: true hljs_languages: - yaml +# Navigation structure nav: - Home: index.md - Getting Started: GettingStarted.md @@ -39,7 +41,7 @@ nav: - Known Hardware Issues: HardwareIssues.md - Translations: Translation.md - Development: Development.md - + # Plugins plugins: - search @@ -47,7 +49,6 @@ plugins: - awesome-pages - git-revision-date - # Markdown Extensions markdown_extensions: - attr_list diff --git a/scripts/deploy.sh b/scripts/deploy.sh index fa89036d..3afd21cc 100755 --- a/scripts/deploy.sh +++ b/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 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