Implement autogeneration of Documentation/README.md

[ia]

• Please check if the PR fulfills these requirements

• The changes have been tested locally
• There are no breaking changes

• What kind of change does this PR introduce?
  Function docs_readme in deploy.sh to generate README.md for Documentation/ based on nav section from ReadTheDocs yml config.

• What is the current behavior?
  When a user opens Documentation/ directory though github interface, there is only listing of files because README.md is missing & not populated.

• What is the new behavior (if this is a feature change)?
  Auto-generated README.md with preserved structure of online documentation for those who is too impatient to click another link and just want to surf through documents using built-in github interface (or let's say github.io subdomain is not available for some reasons, etc.)

• Other information:
  Basically the function automagically with a help of sed takes nav section and converts it into Markdown-compatible README preserving style & structure & adding the headers.

It's more like Proof-of-Concept but it seems it's "production" ready for actively development branch. There is also a temptation to add into .github/workflows/docs.yml something like:

      - name: Update README
        run: ./scripts/deploy.sh docs_readme && git commit Documentation/README.md -m "Documentation/README: autoupdate" && git push

but:

• I'm not sure that it's a good idea to mess up with repo like that;
• nav section is not being updated so often so I guess once in a while README.md update can be just run manually.

What do you think?

[Ralim]

It's more like Proof-of-Concept but it seems it's "production" ready for actively development branch. There is also a temptation to add into .github/workflows/docs.yml something like:

Absolutely do not want any commits from workflows. However I would love one that fails a workflow if this is not up to date.
I.e. run the script and check for a diff, if so abort the workflow run and print a note as to what needs to be done.

Otherwise love the idea of the automation.

[ia]

I would love one that fails a workflow if this is not up to date.
I.e. run the script and check for a diff, if so abort the workflow run and print a note as to what needs to be done.

Implemented & tested locally. Now on run scripts/deploy.sh docs_readme:

• parse nav section and generate README

• compare README.md & README

• if they are the same:

  • remove README
  • exit silently returning 0 to the environment as the indication of success

• if they are different:

  • replace README.md by README
  • show the warning message and exit returning 1 to the environment as the indication of failure/error

  Basically, just adding a call of scripts/deploy.sh docs_readme somewhere to github CI should be enough. However, external tools GNU sed and diff from diffutils are required (since other versions/implementations can behave in different way with the same command-line arguments).

[ia]

And that's how it looks with error message here.