corneel27
diff --git a/‎.github/workflows/check-model-docs.yml‎
Lines changed: 121 additions & 0 deletions b/‎.github/workflows/check-model-docs.yml‎
Lines changed: 121 additions & 0 deletions
diff --git a/‎.gitignore‎
Lines changed: 1 addition & 0 deletions b/‎.gitignore‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎DEVELOP.md‎
Lines changed: 7 additions & 7 deletions b/‎DEVELOP.md‎
Lines changed: 7 additions & 7 deletions
@@ -0,0 +1,121 @@
+name: Check Model Documentation
+
+on:
+  push:
+    paths:
+      - 'dao/prog/config/**/*.py'
+      - 'scripts/generate_docs.py'
+  pull_request:
+    paths:
+      - 'dao/prog/config/**/*.py'
+      - 'scripts/generate_docs.py'
+      - 'SETTINGS.md'
+      - 'config_schema.json'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.ref_name }}-${{ github.event_name }}
+  cancel-in-progress: true
+
+jobs:
+  check-docs:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+    
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+          cache: 'pip'
+      
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          grep '^pydantic' dao/requirements.txt | xargs pip install
+      
+      - name: Generate schema and documentation (with validation)
+        id: generate
+        run: |
+          echo "Generating JSON schema and markdown documentation..."
+          if python scripts/generate_docs.py; then
+            echo "SUCCESS: Schema and documentation generated successfully"
+            echo "validation=success" >> $GITHUB_OUTPUT
+          else
+            echo "ERROR: Generation failed - some fields missing descriptions"
+            echo "validation=failed" >> $GITHUB_OUTPUT
+            exit 1
+          fi
+      
+      - name: Check for changes
+        id: check_changes
+        run: |
+          git diff --exit-code SETTINGS.md config_schema.json || echo "changed=true" >> $GITHUB_OUTPUT
+      
+      - name: Manage PR comment for outdated docs
+        if: github.event_name == 'pull_request'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const MARKER = '## \u26a0\ufe0f Documentation is out of date';
+            const docsOutdated = '${{ steps.check_changes.outputs.changed }}' === 'true';
+
+            const { data: comments } = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+              per_page: 100,
+            });
+
+            const existing = comments.find(c => c.body.includes(MARKER));
+
+            if (docsOutdated) {
+              const body = [
+                MARKER,
+                '',
+                'The generated files `SETTINGS.md` and `config_schema.json` are out of sync with the current Pydantic models.',
+                '',
+                'Please run the following commands locally and push the updated files:',
+                '',
+                '```bash',
+                'python scripts/generate_docs.py',
+                'git add SETTINGS.md config_schema.json',
+                'git commit -m "Update generated documentation"',
+                'git push',
+                '```',
+              ].join('\n');
+
+              if (existing) {
+                await github.rest.issues.updateComment({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  comment_id: existing.id,
+                  body,
+                });
+              } else {
+                await github.rest.issues.createComment({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  issue_number: context.issue.number,
+                  body,
+                });
+              }
+            } else if (existing) {
+              await github.rest.issues.deleteComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: existing.id,
+              });
+            }
+      
+      - name: Fail if docs are outdated
+        if: steps.check_changes.outputs.changed == 'true'
+        run: |
+          echo "ERROR: SETTINGS.md and/or config_schema.json are out of sync with the models."
+          exit 1
+
+      
@@ -18,3 +18,4 @@ __pycache__/
 ../CODEOWNERS
 dao/data/*.csv
 /dao/data/batteries.json
+.venv
@@ -43,17 +43,17 @@ Creating a virtual environment isolates your project dependencies from your syst
 
 **On macOS/Linux:**
 ```bash
-python3 -m venv venv
-source venv/bin/activate
+python3 -m venv .venv
+source .venv/bin/activate
 ```
 
 **On Windows:**
 ```bash
-python -m venv venv
-venv\Scripts\activate
+python -m venv .venv
+.venv\Scripts\activate
 ```
 
-You should see `(venv)` in your terminal prompt, indicating the virtual environment is active.
+You should see `(.venv)` in your terminal prompt, indicating the virtual environment is active.
 
 ### 3. Install Dependencies
 
@@ -146,9 +146,9 @@ From the project root (`day-ahead/`):
 cd /path/to/day-ahead
 
 # Activate your virtual environment if not already active
-source venv/bin/activate  # On macOS/Linux
+source .venv/bin/activate  # On macOS/Linux
 # or
-venv\Scripts\activate     # On Windows
+.venv\Scripts\activate     # On Windows
 
 # In case of manual mip install:
 export PMIP_CBC_LIBRARY=~/day-ahead/dao/prog/miplib/lib/libCbc.so