docs: awkwardness around committing auto-generated files

[jmtd]

We generate documentation files and commit them to the repository so that they are visible/browseable in the github web interface. However, this causes some problems

• there's no guarantee (without additional scripting) that the current state of the templates is represented by the current state of the documentation
• someone might modify an auto-generated file by mistake (risk mitigated by a warning in the files)
• a change to the templates might break the doc generation, but not be noticed
• merges, rebases, and various VCS diff activities become unwieldy with large changes in the auto generated files

This problem might get worse if/when we move to generating more stuff.

I was considering ways this might be improved and one possible solution would be to use a separate git repository for all the auto-generate content. The two repositories could be linked together via git submodule. Here is an example:

• https://github.com/jmtd/application-templates/tree/docs-submodule-test is a fork of the repo with ./docs deleted and a submodule registered in its place, pointing at ...
• ...a new test repository https://github.com/jmtd/test-app-templates-doc-output which has committed the result of running the docs generator in the other repository.

There are likely caveats with this approach, but on the face of it the integration is pretty good on the website front. "Docs" is a clickable hyperlink in the main repository, just as before, and all the generated stuff is browseable right in the github UI.

Github also has the notion of "GitHub pages" which might be a better fit for the ancillary repository. I haven't looked at that, yet.

[jmtd]

Some usage instructions for this demo

$ git clone -b docs-submodule-test [email protected]:jmtd/application-templates.git submodule-test
$ cd submodule-test
$ git submodule update --init

This gives you the main repo checkout and the sub-module checked out inside ./docs.

Modifying the contents of ./docs looks like this from the POV of the parent repository:

$ ./gen_template_docs.py
$ git status
On branch docs-submodule-test
Your branch is up-to-date with 'origin/docs-submodule-test'.
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)
  (commit or discard the untracked or modified content in submodules)

    modified:   docs

no changes added to commit (use "git add" and/or "git commit -a")