ci: bring gh-pages CI up-to-date with other cutter

Closes #54 + Closes #55 + implements  JonasPammer/cookiecutter-pypackage#109

https://github.com/JonasPammer/cookiecutter-pypackage/blob/262462f3ab6ea0f425580a3c02e36cfe3af7d3f8/%7B%7B%20cookiecutter.project_slug%20%7D%7D/.github/workflows/gh-pages.yml

{{ cookiecutter.project_slug }}/.github/workflows/gh-pages.yml

@@ -1,52 +1,96 @@
 ---
-name: build self-contained README
+name: build self-contained READMEs
 
 "on":
   push:
 
 permissions:
   contents: read
 
+# Cancel a currently running workflow from the same PR, branch or tag when a new workflow is triggered for it
+concurrency:
+  group: "{% raw %}${{ github.workflow }}{% endraw %}-{% raw %}${{ github.event.pull_request.number || github.ref }}{% endraw %}"
+  cancel-in-progress: true
+
 jobs:
   gh-pages:
     runs-on: ubuntu-latest
     permissions:
       contents: write
       pages: write
     steps:
+      ### Setup
       - name: check out the codebase
-        uses: actions/checkout@8e5e7e5ab8b370d6c329ec480221332ada57f0ab # v3
+        uses: actions/checkout@v3
 
       - name: setup ruby
         uses: ruby/setup-ruby@v1
         with:
           ruby-version: "2.7.0"
 
+      - name: set up python 3
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.x"
+
+      - name: setup/activate pre-commit cache
+        uses: actions/cache@v3
+        with:
+          path: ~/.cache/pre-commit
+          key: "{% raw %}${{ hashFiles('.pre-commit-config.yaml') }}{% endraw %}"
+
       - name: install asciidoctor and other relevant ruby gems
         run: gem install --no-document asciidoctor asciidoctor-reducer rouge coderay
 
-      - name: Generate README.adoc using ascidoctor-reducer.
-        run: asciidoctor-reducer README.orig.adoc -o README.adoc
-
-      - name: get first line of commit message as variable to be used in next step
+      - name: get first line of commit message as variable
         shell: bash
         run: |
           echo "FIRST_LINE_OF_HEAD_COMMIT_MESSAGE=${HEAD_COMMIT_MESSAGE}" | head -1 >> $GITHUB_ENV
         env:
           HEAD_COMMIT_MESSAGE: "{% raw %}${{ github.event.head_commit.message }}{% endraw %}"
 
-      - name: Commit generated README.
-        uses: stefanzweifel/git-auto-commit-action@3ea6ae190baf489ba007f7c92608f33ce20ef04a # v4
+      ### README.orig.adoc & co.
+      - name: Generate README.adoc using ascidoctor-reducer.
+        run: asciidoctor-reducer README.orig.adoc -o README.adoc
+
+      ### SECURITY.adoc
+      - name: generate SECURITY.xml from SECURITY.adoc using ascidoctor
+        run: asciidoctor -b docbook SECURITY.adoc
+
+      - name: Generate SECURITY.md from SECURITY.xml using pandoc
+        uses: docker://pandoc/core:3.1
+        with:
+          args: "-f docbook -t markdown_strict SECURITY.xml -o SECURITY.md --wrap=none"
+
+      ### Commit
+      - name: add 'changes will be lost' comment to generated files
+        run: |
+          sed -i \
+          '1s|^|This file is being generated by .github/workflows/gh-pages.yml - all local changes will be lost eventually!\n|' \
+          README.adoc README.md SECURITY.md
+
+          sed -i '1s|\(.*\)|<!-- \1 -->|' README.md SECURITY.md
+          sed -i '1s|\(.*\)|// \1|' README.adoc
+
+      - name: pre-commit generated .md files
+        run: |
+          python3 -m pip install pre-commit
+          pre-commit run --files README.md SECURITY.md || true
+          pre-commit run --files README.md SECURITY.md || true
+
+      - name: Commit generated files.
+        uses: stefanzweifel/git-auto-commit-action@v4
         with:
           commit_message: "{% raw %}${{ env.FIRST_LINE_OF_HEAD_COMMIT_MESSAGE }}{% endraw %}\n{% raw %}${{ github.sha }}{% endraw %}"
-          file_pattern: README.adoc
+          file_pattern: README.adoc README.md SECURITY.md
           disable_globbing: true
 
+      ### Deploy README.adoc
       - name: Generate HTML
         run: asciidoctor --backend=html5 --destination-dir docs --out-file index.html README.adoc
 
       - name: Deploy HTML to GitHub Pages (when branch is master).
-        uses: peaceiris/actions-gh-pages@373f7f263a76c20808c831209c920827a82a2847 # v3
+        uses: peaceiris/actions-gh-pages@v3
         with:
           github_token: "{% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %}"
           publish_branch: gh-pages