Add docs

.github/workflows/changelog.yml

@@ -0,0 +1,27 @@
+name: Changelog
+
+on:
+  pull_request:
+    types: [labeled, unlabeled, opened, reopened, synchronize]
+
+permissions:
+  contents: read
+
+env:
+  PR_NUMBER: ${{ github.event.number }}
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v5
+    - name: Check for file
+      if: ${{
+        hashFiles(format('docs/changes/{0}.*.rst', github.event.number)) == '' &&
+        ! contains( github.event.pull_request.labels.*.name, 'skip-changelog')
+        }}
+      run: |
+          ls docs/changes
+          echo ERROR: No changelog file found for pull request \#"$PR_NUMBER"!
+          exit 1
+

.github/workflows/ci.yml

@@ -1,6 +1,3 @@
-# This workflow will install Python dependencies, run tests and lint with a single version of Python
-# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python
-
 name: CI
 
 on:
@@ -21,7 +18,7 @@ jobs:
         python-version: ["3.12", "3.13", "3.14"]
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v5
     - name: Set up Python ${{ matrix.python-version }}
       uses: actions/setup-python@v5
       with:
@@ -31,7 +28,7 @@ jobs:
     - name: Install dependencies
       run: |
         pip install --upgrade pip
-        pip install -e ".[tests]"
+        pip install -e . --group tests
         pip freeze
 
     - name: Test with pytest
@@ -43,18 +40,24 @@ jobs:
       with:
         token: ${{ secrets.CODECOV_TOKEN }}
 
-  # pre-commit:
-  #   runs-on: ubuntu-latest
-  #   strategy:
-  #     matrix:
-  #       python-version: ["3.14"]
-  #
-  #   steps:
-  #   - uses: actions/checkout@v4
-  #   - name: Set up Python ${{ matrix.python-version }}
-  #     uses: actions/setup-python@v5
-  #     with:
-  #       python-version: ${{ matrix.python-version }}
-  #   - name: Display Python version
-  #     run: python -c "import sys; print(sys.version)"
-  #   - uses: pre-commit/action@v3.0.1
+  test_docs:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v5
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.14'
+        architecture: 'x64'
+    - name: Display Python version
+      run: python -c "import sys; print(sys.version)"
+    - name: Install documentation dependencies
+      run: |
+        pip install --upgrade pip
+        pip install -e . --group docs
+        pip freeze
+    - name: Build documentation
+      run: |
+        make -C docs html

.github/workflows/docs.yml

@@ -0,0 +1,90 @@
+name: Docs
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: write
+
+jobs:
+  build_and_release:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v5
+      with:
+        persist-credentials: false
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.14'
+        architecture: 'x64'
+    - name: Display Python version
+      run: python -c "import sys; print(sys.version)"
+    - name: Install dependencies
+      run: |
+        pip install --upgrade pip
+        pip install -e . --group docs
+        pip freeze
+    - name: Build towncrier
+      run: |
+          towncrier build --yes
+
+    - name: Build sphinx docs
+      run: |
+        make -C docs html
+    - name: Compress build
+      run: |
+        sudo apt update --yes && sudo apt install zip --yes
+        cd docs/_build/html && zip -r ../html.zip ./*
+        cd ../../../
+
+    # The App Token creation and git config setup were adapted from:
+    #   - create-github-app-token (https://github.com/actions/create-github-app-token)
+    #     Originally licensed under MIT License. Copyright (c) 2023 Gregor Martynus, Parker Brown.
+    - name: Create GitHub App token
+      id: app-token
+      uses: actions/create-github-app-token@v2
+      with:
+        app-id: ${{ secrets.APP_ID }}
+        private-key: ${{ secrets.APP_PRIVATE_KEY }}
+    - name: Get GitHub App User ID
+      id: get-user-id
+      run: echo "user-id=$(gh api "/users/${{ steps.app-token.outputs.app-slug }}[bot]" --jq .id)" >> "$GITHUB_OUTPUT"
+      env:
+        GH_TOKEN: ${{ steps.app-token.outputs.token }}
+    - name: Setup git config
+      run: |
+        set +x
+        git config --global user.name '${{ steps.app-token.outputs.app-slug }}[bot]'
+        git config --global user.email '${{ steps.get-user-id.outputs.user-id }}+${{ steps.app-token.outputs.app-slug }}[bot]@users.noreply.github.com'
+    - name: Commit and Push
+      env:
+        GH_TOKEN: ${{ steps.app-token.outputs.token }}
+      run: |
+        set +x
+        git add -u docs/changes/
+        git add docs/changes/*.rst
+        git commit -m "Create Changelog for ${{ github.event.release.tag_name }}" || exit 0
+
+        git push "https://x-access-token:${GH_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" HEAD:${{ github.event.release.target_commitish }}
+
+    # Inspired by: https://stackoverflow.com/a/60479844 and https://stackoverflow.com/a/70447517
+    - name: Create SSH key
+      run: |
+        install -m 600 -D /dev/null ~/.ssh/id_key
+        echo "$SSH_PRIVATE_KEY" > ~/.ssh/id_key
+        ssh-keyscan -H "$SSH_HOSTNAME" > ~/.ssh/known_hosts
+      env:
+        SSH_PRIVATE_KEY: ${{secrets.SSH_PRIVATE_KEY}}
+        SSH_HOSTNAME: ${{secrets.SSH_HOSTNAME}}
+    - name: Upload to server
+      run: |
+        ssh -v -i ~/.ssh/id_key "$SSH_USER@$SSH_HOSTNAME" "rm -rf '$SSH_TARGET_DIR/' && mkdir -p '$SSH_TARGET_DIR'"
+        scp -v -i ~/.ssh/id_key -r docs/_build/html.zip "$SSH_USER"@"$SSH_HOSTNAME":"$SSH_TARGET_DIR"/html.zip
+        ssh -v -i ~/.ssh/id_key "$SSH_USER@$SSH_HOSTNAME" "unzip -o '$SSH_TARGET_DIR/html.zip' -d '$SSH_TARGET_DIR' && rm -rf '$SSH_TARGET_DIR/html.zip'"
+      env:
+        SSH_USER: ${{secrets.SSH_USER}}
+        SSH_HOSTNAME: ${{secrets.SSH_HOSTNAME}}
+        SSH_TARGET_DIR: ${{secrets.SSH_TARGET_DIR}}

.gitignore

@@ -80,7 +80,7 @@ instance/
 
 # Sphinx documentation
 docs/_build/
-docs/build
+docs/_generated
 
 # PyBuilder
 .pybuilder/

.pre-commit-config.yaml

@@ -2,6 +2,12 @@
 #   - pyvisgen (https://github.com/radionets-project/pyvisgen/blob/main/.pre-commit-config.yaml)
 #     Originally licensed under MIT License. Copyright (c) 2021 radionets-project.
 
+default_install_hook_types:
+  - pre-commit
+  - commit-msg
+
+default_stages: [pre-commit]
+
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v6.0.0
@@ -31,3 +37,9 @@ repos:
     rev: v2.4.1
     hooks:
       - id: codespell
+  - repo: https://github.com/compilerla/conventional-pre-commit
+    rev: v4.3.0
+    hooks:
+      - id: conventional-pre-commit
+        stages: [ commit-msg ]
+        args: [--verbose]

ASSETS_LEGAL.rst

@@ -1,17 +1,16 @@
-==============
 Asset Licenses
-==============
+--------------
 
 This file documents the sources and licenses of additional media used within this repository,
 which is not inside of the main source code of the module.
 
   **Backpy Logo and Icon**
 
-  =================== ===================================================================================================================================================================
-  **File**            `</assets/backpy_logo.png>`_ `</assets/backpy_icon.png>`_
+  =================== ==========================================================================================================================================================================================================================================================================================
+  **File**            `</docs/_static/logos/backpy_logo_dark.png>`_ `</docs/_static/logos/backpy_logo_light.png>`_ `</docs/_static/logos/backpy_icon_dark.png>`_ `</docs/_static/logos/backpy_icon_light.png>`_ `</docs/_static/logos/backpy_header_dark.png>`_ `</docs/_static/logos/backpy_header_light.png>`_
   **Author**          `<https://github.com/tgross03>`_
   **Used Elements**   | `Font Awesome 'database' icon <https://fontawesome.com/icons/database?f=classic&s=solid>`_ (License: `CC-4.0-BY <https://creativecommons.org/licenses/by/4.0/>`_)
                       | `Catppuccin Colors <https://catppuccin.com/palette/>`_ (License: `MIT License <https://catppuccin.com/licensing/>`_)
-  =================== ===================================================================================================================================================================
+  =================== ==========================================================================================================================================================================================================================================================================================