sv/IronOS
1
0
Fork 0
forked from me/IronOS
Code Pull Requests Activity

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

Browse Source 
* 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
This commit is contained in:
Ivan Zorin
2023-07-11 02:36:05 +03:00
committed by GitHub
parent cd7696b66f
commit 4649df6914
4 changed files with 102 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

66
scripts/deploy.sh
View File

@@ -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