doc: major documentation refactoring, update github actions

.github/workflows/compliance.yml

@@ -0,0 +1,38 @@
+name: Build Sphinx Doc
+
+on:
+  pull_request:
+
+jobs:
+  build-doc:
+    runs-on: ubuntu-latest
+    steps:
+
+    - name: Checkout
+      uses: actions/checkout@v4
+
+    - name: Install Packages
+      run: |
+        sudo apt-get update
+        sudo apt-get install plantuml tox python3-pip -y
+
+    - name: Build static site with Tox
+      run: |
+        cd doc
+        tox -e py3-html
+
+    - name: Deploy Preview
+      uses: peaceiris/actions-gh-pages@v4
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: doc/build/html
+        destination_dir: 'previews/${{ github.event.number }}'
+
+    - name: Create status check with preview link
+      run: |
+        PREVIEW_URL="https://flownexus-lwm2m.github.io/waterlevel_monitor/previews/${{ github.event.number }}"
+        PAYLOAD=$(echo '{}' | jq --arg name 'Documentation Preview' --arg url "${PREVIEW_URL}" '{"name": $name, "head_sha": "${{ github.event.pull_request.head.sha }}", "details_url": $url, "status": "completed", "conclusion": "success", "output": {"title": $name, "summary": "Preview available at", "text": $url}}')
+        curl -s -H "Authorization: token ${{ secrets.GITHUB_TOKEN }}" \
+             -H "Content-Type: application/json" \
+             -X POST -d "${PAYLOAD}" \
+             "https://api.github.com/repos/${{ github.repository }}/check-runs"

.github/workflows/deploy.yml

@@ -0,0 +1,30 @@
+name: Build and Deploy Sphinx Doc
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install Packages
+        run: |
+          sudo apt-get update
+          sudo apt-get install plantuml toxpython3-pip -y
+
+      - name: Build static site with Tox
+        run: |
+          cd doc
+          tox -e py3-html
+
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: doc/build/html

doc/requirements.txt

@@ -1,4 +1,4 @@
-Sphinx==7.2.6
-sphinx-rtd-theme==2.0.0
+Sphinx==8.1.3
+sphinx-book-theme==1.1.3
 sphinxcontrib-plantuml
 codespell

doc/source/_static/custom.css

@@ -0,0 +1,12 @@
+.highlight .gp {
+    color: #ffa200;
+    font-weight: bold;
+}
+
+/* Fixes miscalculationg about the margin, which causes a scrollbar between
+ * the primary sidebar and the content
+ */
+#rtd-footer-container {
+    margin-top: 0px !important;
+    margin-bottom: 0px !important;
+}