From 4649df69145d0f3764d2df29439e232944ccce52 Mon Sep 17 00:00:00 2001 From: Ivan Zorin Date: Tue, 11 Jul 2023 02:36:05 +0300 Subject: [PATCH] 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 | 5 ++- Documentation/README.md | 29 +++++++++++++++++ scripts/IronOS-mkdocs.yml | 9 +++--- scripts/deploy.sh | 66 ++++++++++++++++++++++++++++++++++++-- 4 files changed, 102 insertions(+), 7 deletions(-) create mode 100644 Documentation/README.md diff --git a/.github/workflows/push.yml b/.github/workflows/push.yml index 765910f9d8..9f904a2a4d 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 0000000000..878072984d --- /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 9514aa1b1c..24515f68b7 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 fa89036d53..3afd21cc2f 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