docs: expand release_candidate2 documentation

.github/workflows/mkdocs-preview.yml

@@ -0,0 +1,89 @@
+# Build MkDocs for pull requests and publish a preview under /preview/pr-<number>/
+# on the existing gh-pages branch. Production root and /beta/ are preserved.
+
+name: Publish docs preview
+
+on:
+  pull_request:
+    branches:
+      - release_candidate2
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "requirements-docs.txt"
+      - ".github/workflows/mkdocs-preview.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+concurrency:
+  group: gh-pages-deploy
+  cancel-in-progress: false
+
+jobs:
+  build-and-deploy:
+    if: github.event_name == 'workflow_dispatch' || github.event.pull_request.head.repo.full_name == github.repository
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+          cache-dependency-path: requirements-docs.txt
+
+      - name: Install MkDocs
+        run: pip install -r requirements-docs.txt
+
+      - name: Set preview URL
+        id: preview
+        shell: bash
+        run: |
+          if [ "${{ github.event_name }}" = "pull_request" ]; then
+            PR_NUMBER="${{ github.event.pull_request.number }}"
+          else
+            PR_NUMBER="manual-${GITHUB_RUN_NUMBER}"
+          fi
+          echo "number=${PR_NUMBER}" >> "$GITHUB_OUTPUT"
+          echo "url=https://looselab.github.io/ROBIN/preview/pr-${PR_NUMBER}/" >> "$GITHUB_OUTPUT"
+
+      - name: Build site
+        env:
+          PREVIEW_SITE_URL: ${{ steps.preview.outputs.url }}
+        run: |
+          cp mkdocs.yml mkdocs.preview.yml
+          python - <<'PY'
+          from pathlib import Path
+          import os
+          p = Path("mkdocs.preview.yml")
+          text = p.read_text()
+          lines = text.splitlines()
+          preview_url = os.environ["PREVIEW_SITE_URL"]
+          replaced = False
+          for i, line in enumerate(lines):
+              if line.startswith("site_url:"):
+                  lines[i] = f"site_url: {preview_url}"
+                  replaced = True
+                  break
+          if not replaced:
+              lines.insert(0, f"site_url: {preview_url}")
+          p.write_text("\n".join(lines) + "\n")
+          PY
+          mkdocs build --strict -f mkdocs.preview.yml
+
+      - name: Add .nojekyll
+        run: touch site/.nojekyll
+
+      - name: Deploy preview to GitHub Pages branch
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          folder: site
+          branch: gh-pages
+          target-folder: preview/pr-${{ steps.preview.outputs.number }}
+          clean: true
+
+      - name: Preview URL
+        run: |
+          echo "Preview: ${{ steps.preview.outputs.url }}"

LICENSE

@@ -0,0 +1,34 @@
+Creative Commons Attribution-NonCommercial 4.0 International
+
+Copyright (c) 2023-present Matt Loose
+
+This work is licensed under the Creative Commons Attribution-NonCommercial 4.0 International License (CC BY-NC 4.0).
+
+You are free to:
+
+Share — copy and redistribute the material in any medium or format.
+Adapt — remix, transform, and build upon the material.
+
+Under the following terms:
+
+Attribution — You must give appropriate credit, provide a link to the license, and indicate if changes were made. You may do so in any reasonable manner, but not in any way that suggests the licensor endorses you or your use.
+
+NonCommercial — You may not use the material for commercial purposes.
+
+No additional restrictions — You may not apply legal terms or technological measures that legally restrict others from doing anything the license permits.
+
+The licensor cannot revoke these freedoms as long as you follow the license terms.
+
+Notices:
+
+You do not have to comply with the license for elements of the material in the public domain or where your use is permitted by an applicable exception or limitation.
+
+No warranties are given. The license may not give you all of the permissions necessary for your intended use. For example, other rights such as publicity, privacy, or moral rights may limit how you use the material.
+
+The complete legal code for the Creative Commons Attribution-NonCommercial 4.0 International License is available at:
+https://creativecommons.org/licenses/by-nc/4.0/legalcode
+
+License summary:
+https://creativecommons.org/licenses/by-nc/4.0/
+
+Third-party software, models, data, and other resources included with or used by ROBIN remain subject to their respective licences and terms.