From 001a063d91899dd5ac8ccf4b5b71b4db0c1db002 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Martin=20M=C3=B8ldrup?= <mmoeldrup@grundfos.com>
Date: Sun, 12 Jan 2025 16:07:06 +0100
Subject: [PATCH] Add build for mkdocs into github pages

---
 .github/workflows/mkdocs.yml              | 65 +++++++++++++++++++++++
 .github/workflows/release.yaml            | 25 ++++++++-
 docs/gen_ref_pages.py                     | 11 ++--
 pyproject.toml                            |  2 +-
 snappylapy/__init__.py                    |  2 +-
 snappylapy/{plugin.py => _plugin.py}      |  2 +-
 snappylapy/constants.py                   |  3 ++
 snappylapy/{snappylapy.py => fixtures.py} | 11 +++-
 8 files changed, 111 insertions(+), 10 deletions(-)
 create mode 100644 .github/workflows/mkdocs.yml
 rename snappylapy/{plugin.py => _plugin.py} (98%)
 rename snappylapy/{snappylapy.py => fixtures.py} (90%)

diff --git a/.github/workflows/mkdocs.yml b/.github/workflows/mkdocs.yml
new file mode 100644
index 0000000..7eeef49
--- /dev/null
+++ b/.github/workflows/mkdocs.yml
@@ -0,0 +1,65 @@
+name: Generate documentation and deploy to GitHub pages
+on:
+  # Documentation can be either manually updated or is automatically updated when pushed to main branch
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+
+# Make sure deploy-pages has necessary permissions to deploy to GitHub Pages
+permissions:
+  pages: write
+  id-token: write
+
+# Cancel older deploy workflow when more than one is running
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    name: Build and deploy documentation site
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deploy.outputs.page_url }} # Output URL after the workflow has finished
+    steps:
+      # Checkout repository including submodules
+      - name: Checkout
+        id: checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: true
+
+      # Setup Python 3.9
+      - name: Setup Python
+        id: python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.9'
+
+      # Install dependencies using Poetry
+      - uses: Gr1N/setup-poetry@v9
+      - uses: actions/cache@v4
+        with:
+            path: ~/.cache/pypoetry/virtualenvs
+            key: ${{ runner.os }}-poetry-${{ hashFiles('poetry.lock') }}
+      - run: poetry --version
+      - run: poetry install
+
+      # Build documentation to ./site/ directory
+      - name: Build Documentation
+        id: build
+        run: poetry run mkdocs build
+
+      # Upload artifact from the ./site/ directory using the expected format for GitHub Pages
+      - name: Upload Artifact
+        id: upload
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./site/
+
+      # Use previously uploaded artifact to deploy to GitHub Pages
+      - name: Deploy
+        id: deploy
+        uses: actions/deploy-pages@v4
\ No newline at end of file
diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml
index 73bd9e8..718adee 100644
--- a/.github/workflows/release.yaml
+++ b/.github/workflows/release.yaml
@@ -66,6 +66,27 @@ jobs:
             echo "The new version $NEW_VERSION is greater than the latest version $LATEST_VERSION on PyPI."
           fi
 
+  read_changelog:
+    needs: details
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Read Changelog
+        id: changelog
+        run: |
+          if [ ! -f "README.md" ]; then
+            echo "README.md file not found."
+            exit 1
+          fi
+          CHANGELOG=$(awk '/^## \['${{ needs.details.outputs.new_version }}'\]/,/^## \[/' README.md | sed '1d;$d')
+          if [ -z "$CHANGELOG" ]; then
+            echo "Changelog for version ${{ needs.details.outputs.new_version }} not found."
+            exit 1
+          fi
+          echo "Changelog read as: $CHANGELOG"
+          echo "CHANGELOG=$CHANGELOG" >> $GITHUB_ENV
+                
   setup_and_build:
     needs: [details, check_pypi]
     runs-on: ubuntu-latest
@@ -119,7 +140,7 @@ jobs:
 
   github_release:
     name: Create GitHub Release
-    needs: [setup_and_build, details]
+    needs: [setup_and_build, details, read_changelog]
     runs-on: ubuntu-latest
     permissions:
       contents: write
@@ -140,4 +161,4 @@ jobs:
         env:
           GH_TOKEN: ${{ github.token }}
         run: |
-          gh release create ${{ needs.details.outputs.tag_name }} dist/* --title ${{ needs.details.outputs.tag_name }} --generate-notes
+          gh release create ${{ needs.details.outputs.tag_name }} dist/* --title ${{ needs.details.outputs.tag_name }} --generate-notes --notes "${{ env.CHANGELOG }}"
diff --git a/docs/gen_ref_pages.py b/docs/gen_ref_pages.py
index cdbae98..1332bf0 100644
--- a/docs/gen_ref_pages.py
+++ b/docs/gen_ref_pages.py
@@ -13,10 +13,13 @@
     full_doc_path = Path("reference", doc_path)
     parts = list(path.relative_to(src.parent).with_suffix("").parts)
     if path.stem == "__init__":
-        doc_path = doc_path.with_name("index.md")
-        full_doc_path = full_doc_path.with_name("index.md")
-        # delete the "__init__" element
-        parts.remove("__init__")
+        # doc_path = doc_path.with_name("index.md")
+        # full_doc_path = full_doc_path.with_name("index.md")
+        # # delete the "__init__" element
+        # parts.remove("__init__")
+        continue
+    if path.stem.startswith("_"):
+        continue
 
     nav[parts] = doc_path.as_posix()
 
diff --git a/pyproject.toml b/pyproject.toml
index f3f7429..40d9a8c 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -52,4 +52,4 @@ requires = ["poetry-core"]
 build-backend = "poetry.core.masonry.api"
 
 [tool.poetry.plugins."pytest11"]
-"snappylapy" = "snappylapy.plugin"
+"snappylapy" = "snappylapy._plugin"
diff --git a/snappylapy/__init__.py b/snappylapy/__init__.py
index ee7d017..cd57895 100644
--- a/snappylapy/__init__.py
+++ b/snappylapy/__init__.py
@@ -1,7 +1,7 @@
 """Define the public api for the snappylapy package."""
 import pytest
 pytest.register_assert_rewrite("snappylapy.expectation_classes.base_snapshot")
-from .snappylapy import Expect, LoadSnapshot
+from .fixtures import Expect, LoadSnapshot
 
 
 __all__ = ["Expect", "LoadSnapshot"]
diff --git a/snappylapy/plugin.py b/snappylapy/_plugin.py
similarity index 98%
rename from snappylapy/plugin.py
rename to snappylapy/_plugin.py
index 5066556..d1ccd91 100644
--- a/snappylapy/plugin.py
+++ b/snappylapy/_plugin.py
@@ -1,7 +1,7 @@
 """Pytest plugin for snapshot testing."""
 import pytest
 from snappylapy import Expect, LoadSnapshot
-from snappylapy.snappylapy import Settings
+from snappylapy.fixtures import Settings
 
 
 @pytest.fixture()
diff --git a/snappylapy/constants.py b/snappylapy/constants.py
index cc4f3b8..b2636f2 100644
--- a/snappylapy/constants.py
+++ b/snappylapy/constants.py
@@ -1,4 +1,7 @@
 """Read-only constants."""
 
 SNAPSHOT_DIR_NAME = "__snapshots__"
+"""Snapshot directory name."""
+
 TEST_RESULTS_DIR_NAME = "__test_results__"
+"""Test results directory name."""
diff --git a/snappylapy/snappylapy.py b/snappylapy/fixtures.py
similarity index 90%
rename from snappylapy/snappylapy.py
rename to snappylapy/fixtures.py
index ae815b0..33f84f5 100644
--- a/snappylapy/snappylapy.py
+++ b/snappylapy/fixtures.py
@@ -1,4 +1,13 @@
-"""Snapshot testing for Python."""
+"""
+The fixtures module provides classes returned by fixtures registred by pytest in snappylapy.
+
+Snappylapy provides the following fixtures.
+
+- expect: Expect
+    - Allows for validating various expectations on the test results and do snapshot testing.
+- load_snapshot: LoadSnapshot
+    - Allows loading from a snapshot created by another test.
+"""
 from __future__ import annotations
 
 import pathlib