39 explore automatic documentation generation

.github/workflows/ci.yml

@@ -1,28 +1,57 @@
 name: OpenModels CI
 
 permissions:
-  contents: write
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
 
 on:
   push:
     branches: [main]
   pull_request:
     branches: [main]
+  workflow_dispatch:
 
 jobs:
+  setup:
+    runs-on: ubuntu-latest
+    outputs:
+      matrix: ${{ steps.set-matrix.outputs.matrix }}
+    steps:
+      - id: set-matrix
+        run: |
+          if [ "${{ github.event_name }}" == "pull_request" ]; then
+            echo 'matrix=["3.10","3.11","3.12","3.13"]' >> "$GITHUB_OUTPUT"
+          else
+            echo 'matrix=["3.11"]' >> "$GITHUB_OUTPUT"
+          fi
+
   test:
+    needs: setup
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ['3.10', '3.11', '3.12', '3.13']
+        python-version: ${{ fromJson(needs.setup.outputs.matrix) }}
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
 
+      - name: Cache Poetry dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cache/pypoetry/virtualenvs
+            ~/.cache/pip
+          key: ${{ runner.os }}-poetry-${{ matrix.python-version }}-${{ hashFiles('poetry.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-poetry-${{ matrix.python-version }}-
+
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
@@ -42,15 +71,11 @@ jobs:
       - name: Run type checking
         run: poetry run mypy openmodels
 
-      - name: Run formatting
-        run: |
-          poetry run black openmodels
-          git diff --exit-code
+      - name: Check formatting
+        run: poetry run black --check openmodels
 
       - name: Run linting
-        run: |
-          poetry run black --check openmodels
-          poetry run flake8 openmodels
+        run: poetry run flake8 openmodels
 
       - name: Check for leftover debug print statements
         run: |
@@ -63,12 +88,22 @@ jobs:
     needs: test
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: '3.11'
 
+      - name: Cache Poetry dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cache/pypoetry/virtualenvs
+            ~/.cache/pip
+          key: ${{ runner.os }}-poetry-3.11-${{ hashFiles('poetry.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-poetry-3.11-
+
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
@@ -87,13 +122,13 @@ jobs:
   publish-test:
     needs: build
     runs-on: ubuntu-latest
-    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    if: github.event_name == 'workflow_dispatch'
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: '3.11'
 
@@ -108,7 +143,20 @@ jobs:
           name: python-package-distributions
           path: dist/
 
+      - name: Check if version already published to TestPyPI
+        id: check-version
+        run: |
+          current_version=$(poetry version -s)
+          status=$(curl -s -o /dev/null -w "%{http_code}" "https://test.pypi.org/pypi/openmodels/${current_version}/json")
+          if [ "$status" == "200" ]; then
+            echo "Version $current_version already exists on TestPyPI, skipping publish."
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "skip=false" >> "$GITHUB_OUTPUT"
+          fi
+
       - name: Publish package to TestPyPI
+        if: steps.check-version.outputs.skip == 'false'
         env:
           TEST_PYPI_API_TOKEN: ${{ secrets.TEST_PYPI_API_TOKEN }}
         run: |

.github/workflows/docs.yml

@@ -0,0 +1,67 @@
+name: Deploy Docs
+
+on:
+    push:
+        branches:
+            - main
+        paths:
+            - 'docs/**'
+            - 'openmodels/**'
+            - 'pyproject.toml'
+            - '.github/workflows/docs.yml'
+    workflow_dispatch:
+
+permissions:
+    contents: read
+    pages: write
+    id-token: write
+
+concurrency:
+    group: pages
+    cancel-in-progress: false
+
+jobs:
+    build:
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v6
+
+            - name: Set up Python
+              uses: actions/setup-python@v6
+              with:
+                  python-version: "3.12"
+
+            - name: Cache Poetry dependencies
+              uses: actions/cache@v4
+              with:
+                  path: |
+                      ~/.cache/pypoetry/virtualenvs
+                      ~/.cache/pip
+                  key: ${{ runner.os }}-docs-${{ hashFiles('poetry.lock') }}
+                  restore-keys: |
+                      ${{ runner.os }}-docs-
+
+            - name: Install dependencies
+              run: |
+                  python -m pip install --upgrade pip
+                  pip install poetry
+                  poetry install --with docs
+
+            - name: Build docs
+              run: poetry run sphinx-build docs docs/_build/html
+
+            - name: Upload artifact
+              uses: actions/upload-pages-artifact@v4
+              with:
+                  path: docs/_build/html
+
+    deploy:
+        needs: build
+        runs-on: ubuntu-latest
+        environment:
+            name: github-pages
+            url: ${{ steps.deployment.outputs.page_url }}
+        steps:
+            - name: Deploy to GitHub Pages
+              id: deployment
+              uses: actions/deploy-pages@v4

.github/workflows/publish-pypi.yml

@@ -1,5 +1,8 @@
 name: Publish to PyPI
 
+permissions:
+  contents: read
+
 on:
   workflow_dispatch:
     inputs:
@@ -12,10 +15,10 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: '3.11'
 

.github/workflows/sklearn-compat.yml

@@ -1,14 +1,13 @@
 name: scikit-learn compatibility
 
+permissions:
+  contents: read
+
+concurrency:
+  group: sklearn-compat-${{ github.ref }}
+  cancel-in-progress: true
+
 on:
-  push:
-    branches: [main]
-    paths:
-      - 'openmodels/**'
-      - 'test/**'
-      - '.github/workflows/sklearn-compat.yml'
-  schedule:
-    - cron: '0 6 * * 1'   # weekly, Monday 06:00 UTC
   workflow_dispatch:
 
 jobs:
@@ -23,13 +22,23 @@ jobs:
           - sklearn-version: '1.8.0'
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Set up Python 3.12
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: '3.12'
 
+      - name: Cache Poetry dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cache/pypoetry/virtualenvs
+            ~/.cache/pip
+          key: ${{ runner.os }}-sklearn-compat-${{ matrix.sklearn-version }}-${{ hashFiles('poetry.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-sklearn-compat-${{ matrix.sklearn-version }}-
+
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip

.gitignore

@@ -56,4 +56,7 @@ test/temp/*.json
 .coverage
 .coverage.*
 CLAUDE.md
-.tox/
+.tox/
+# Sphinx documentation build output #
+##################################
+docs/_build/

Taskfile.yml

@@ -49,4 +49,14 @@ tasks:
   build:
     desc: Build the project
     cmds:
-      - "poetry build"
+      - "poetry build"
+
+  docs:html-all:
+    desc: Build the Sphinx documentation (clean + full rebuild)
+    cmds:
+      - "poetry run sphinx-build -b html docs docs/_build/html"
+
+  docs:serve:
+    desc: Serve the documentation locally on port 8000
+    cmds:
+      - "poetry run python -m http.server 8000 --directory docs/_build/html"

docs/api.md

@@ -0,0 +1,59 @@
+# API Reference
+
+## Core
+
+```{eval-rst}
+.. automodule:: openmodels.core
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+## Protocols
+
+```{eval-rst}
+.. automodule:: openmodels.protocols
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+## Format Registry
+
+```{eval-rst}
+.. automodule:: openmodels.format_registry
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+## Serializers
+
+### Sklearn Serializer
+
+```{eval-rst}
+.. automodule:: openmodels.serializers.sklearn.sklearn_serializer
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+## Converters
+
+### JSON Converter
+
+```{eval-rst}
+.. automodule:: openmodels.converters.json_converter
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+### Pickle Converter
+
+```{eval-rst}
+.. automodule:: openmodels.converters.pickle_converter
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```