finalize automation/CI workflows:

- build markdown/HTML versions, use separate makefile targets/hecat configuration files for each export format/push task
- add non-free.md generation step to markdown export hecat configuration file
- add makefile targets to push exports to https://github.com/awesome-selfhosted/awesome-selfhosted and https://github.com/nodiscc/awesome-selfhosted-html-preview
- install: install sphinx <7 directly using pip since it can't be installed from setup.py https://github.com/sphinx-doc/sphinx/issues/11130
- pin sphinx to version <7, sphinx-design is not compatible with sphinx 7 https://github.com/executablebooks/sphinx-design/issues/130
- add sphinx configuration file
- tools/makefile: monkeypatch furo theme to display build tools and license link in footer (furo/sphinx does not provide a way to customize this https://github.com/pradyunsg/furo/discussions/612)
- fix dependencies between makefile targets
- setup/document SSH deploy keys usage
- each repository requires a different deploy key, trying to add a deploy key to repo B, which has already been added to repo A results in error 'this key already exists'
- set git remote URL to use ssh URIs before push (required to use SSH deploy keys)
- when referencing an environment secret, environment: key must be defined explicitly for the step (https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment#referencing-an-environment)
- use a single SSH key file/no ssh-agent, else git push will try to use the first registered key and fail with permission denied when trying to push to the HTML repository
- use variables to identify target repos
- use temporary repositories as push destination

.github/workflows/build.yml

@@ -9,10 +9,35 @@ concurrency:
   group: build-${{ github.ref }}
   cancel-in-progress: true
 
+# This job requires deploy keys to be added to target repositories (https://docs.github.com/en/authentication/connecting-to-github-with-ssh/managing-deploy-keys)
+# Generate deploy keys locally:
+# $ ssh-keygen -t rsa -f awesome-selfhosted-deploy-key -C awesome-selfhosted-deploy-key
+# $ ssh-keygen -t rsa -f awesome-selfhosted-html-deploy-key -C awesome-selfhosted-html-deploy-key
+# Paste the contents of awesome-selfhosted-deploy-key.pub to https://github.com/nodiscc/awesome-selfhosted/settings/keys/new, name: awesome-selfhosted-deploy-key, allow write access
+# Paste the contents of awesome-selfhosted-html-deploy-key.pub to https://github.com/nodiscc/awesome-selfhosted-html-preview/settings/keys/new, name: awesome-selfhosted-html-deploy-key
+# Access https://github.com/awesome-selfhosted/awesome-selfhosted-data/settings/environments, create new environment with name: production
+#   - deployment branches: selected branches
+#   - add deployment branch rule: branch name pattern: master
+#   - environment secrets: add secret with name: SSH_MARKDOWN_DEPLOY_KEY, and value: paste the contents of awesome-selfhosted-deploy-key
+#   - environment secrets: add secret with name: SSH_HTML_DEPLOY_KEY, and value: paste the contents of awesome-selfhosted-html-deploy-key
+
 jobs:
   build:
+    environment: production
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
       - run: make awesome_lint
-      - run: make export
+      - run: make export_markdown export_html
+      - name: setup markdown repository SSH deploy key
+        run: |
+          mkdir -p ~/.ssh
+          echo "${{ secrets.SSH_MARKDOWN_DEPLOY_KEY }}" > ~/.ssh/id_rsa
+          chmod 0600 ~/.ssh/id_rsa
+      - run: make push_markdown
+      - name: setup HTML repository SSH deploy key
+        run: |
+          mkdir -p ~/.ssh
+          echo "${{ secrets.SSH_HTML_DEPLOY_KEY }}" > ~/.ssh/id_rsa
+          chmod 0600 ~/.ssh/id_rsa
+      - run: make push_html

.github/workflows/daily-checks.yml

@@ -1,4 +1,4 @@
-name: dead links and unmaintained projects checks
+name: dead links/unmaintained projects checks
 
 on:
   schedule:

.github/workflows/pull-request.yml

@@ -14,4 +14,4 @@ jobs:
     steps:
       - uses: actions/checkout@v3
       - run: make awesome_lint
-      - run: make export
+      - run: make export_markdown