Add build for mkdocs into github pages

.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

.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 }}"

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()
 

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"

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"]

snappylapy/plugin.py → 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()

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."""

snappylapy/snappylapy.py → 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