feat(dx): Add Makefile and setup guide (#96)

.github/workflows/append_pr_history.yml

@@ -0,0 +1,43 @@
+# This GitHub Actions workflow appends PR history to docs/PR_HISTORY.md after a PR is merged into main or a release branch.
+
+name: Append PR History
+
+on:
+  pull_request:
+    types: [closed]
+    branches:
+      - main
+      - 'release/**'
+
+jobs:
+  append-pr-history:
+    if: github.event.pull_request.merged == true
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # Required to push a commit
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Ensure full git history for diff
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Append PR history
+        env:
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          PR_TITLE: ${{ github.event.pull_request.title }}
+          PR_MERGER: ${{ github.event.pull_request.merged_by.login }}
+          PR_DESCRIPTION: ${{ github.event.pull_request.body }}
+        run: python scripts/append_pr_history.py
+
+      - name: Commit and push PR_HISTORY.md
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add docs/PR_HISTORY.md
+          git commit -m "docs: update PR history for PR #${{ github.event.pull_request.number }}" || echo "No changes to commit"
+          git push

.github/workflows/ci.yml

@@ -0,0 +1,56 @@
+name: CI - Lint, Test, and Docs
+
+on:
+  pull_request:
+    branches: [ main, fix-readthedocs, docs-sidebar-recipes-from-fix-readthedocs ]
+  push:
+    branches: [ main, fix-readthedocs, docs-sidebar-recipes-from-fix-readthedocs ]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install poetry
+          poetry install --with dev,docs
+      - name: Lint with flake8
+        run: poetry run flake8 src/ tests/
+
+  test:
+    runs-on: ubuntu-latest
+    needs: lint
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install poetry
+          poetry install --with dev,docs
+      - name: Run tests
+        run: poetry run pytest tests/
+
+  docs:
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install poetry
+          poetry install --with docs
+      - name: Build documentation
+        run: poetry run mkdocs build --strict
+
+# Only allow merge if all jobs succeed (enforced by branch protection rules in GitHub settings)

.github/workflows/mkdocs_link_check.yml

@@ -0,0 +1,37 @@
+# This workflow checks for broken links in the built MkDocs site using mkdocs-htmlproofer-plugin.
+# It runs on every push and pull request to main and release branches.
+
+name: MkDocs Broken Link Check
+
+on:
+  push:
+    branches:
+      - main
+      - 'release/**'
+  pull_request:
+    branches:
+      - main
+      - 'release/**'
+
+jobs:
+  link-check:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+
+      - name: Install dependencies
+        run: |
+          pip install -r requirements.txt || true
+          pip install mkdocs-htmlproofer-plugin
+
+      - name: Build docs and check links
+        run: |
+          mkdocs build

.gitignore

@@ -1,50 +1,8 @@
-# Virtual Environment
-.venv/
-
-# Python cache
-__pycache__/
-*.py[cod]
-*$py.class
-
-# C extensions
-*.so
-
-# Distribution / packaging
-build/
-dist/
-downloads/
-eggs/
-.eggs/
-lib/
-lib64/
-parts/
-sdist/
-var/
-wheels/
-*.egg-info/
-.installed.cfg
-*.egg
-
-# MkDocs
-site/
+.idea/local-data-platform.iml
+.idea/misc.xml
+.idea/modules.xml
+.idea/vcs.xml
+.idea/workspace.xml
+**/__pycache__/
 docs/_build/
-
-# Pytest
-.pytest_cache/
-.mypy_cache/
-.coverage
-
-# OS / Editor specific
-.DS_Store
-.idea/
-*.swp
-
-# Temporary files
-*.bak
-
-# Temporary directories
-src/tmp/
-src/local_data_platform/tmp/
-
-# Old config files
-mkdocs.yaml
+site/

Makefile

@@ -0,0 +1,84 @@
+# Makefile for the local-data-platform project
+
+.PHONY: help all install reinstall lint test docs serve-docs clean generate-docs verify-pymdownx
+
+# Default target to show help.
+help:
+	@echo "Usage: make [target]"
+	@echo ""
+	@echo "Targets:"
+	@echo "  all           Run all quality checks (lint and test)."
+	@echo "  help          Show this help message."
+	@echo "  install       Install project dependencies using Poetry."
+	@echo "  reinstall     Force a clean re-installation of all dependencies."
+	@echo "  lint          Run flake8 linter on the project."
+	@echo "  test          Run pytest tests."
+	@echo "  generate-docs Generate dynamic documentation content (e.g., issue lists)."
+	@echo "  docs          Build the MkDocs documentation."
+	@echo "  serve-docs    Build and serve the documentation locally on http://localhost:8000."
+	@echo "  clean         Remove temporary build files and caches."
+	@echo "  verify-pymdownx  Verify a specific documentation dependency."
+
+POETRY_RUN := poetry run
+
+# ==============================================================================
+# Development Setup
+# ==============================================================================
+
+install:
+	@echo "--> Installing dependencies with Poetry..."
+	poetry install --with dev,docs
+
+reinstall:
+	@echo "--> Removing existing virtual environment to ensure a clean state..."
+	@poetry env remove $$(poetry env info --path) || echo "No virtualenv found to remove, continuing..."
+	@echo "--> Reinstalling all dependencies from scratch..."
+	@$(MAKE) install
+
+# ==============================================================================
+# Quality & Testing
+# ==============================================================================
+
+all: lint test
+	@echo "--> All quality checks passed successfully."
+
+lint:
+	@echo "--> Linting with flake8..."
+	$(POETRY_RUN) flake8 src/ tests/
+
+test:
+	@echo "--> Running tests with pytest..."
+	$(POETRY_RUN) pytest tests/
+
+# ==============================================================================
+# Documentation
+# ==============================================================================
+
+generate-docs:
+	@echo "--> Generating dynamic documentation content..."
+	$(POETRY_RUN) python3 docs/scripts/generate_issue_list.py
+
+docs:
+	@$(MAKE) generate-docs
+	@echo "--> Building documentation..."
+	$(POETRY_RUN) mkdocs build --strict
+
+serve-docs:
+	@$(MAKE) generate-docs
+	@echo "--> Serving documentation..."
+	$(POETRY_RUN) mkdocs serve
+
+# ==============================================================================
+# Cleaning
+# ==============================================================================
+
+clean:
+	@echo "--> Cleaning up build artifacts and caches..."
+	@find . -type f -name "*.py[co]" -delete
+	@find . -type d -name "__pycache__" -exec rm -rf {} +
+	@rm -rf .pytest_cache .mypy_cache build dist *.egg-info site
+
+# Verify if pymdownx.toc is importable within the Poetry environment
+verify-pymdownx:
+	@echo "--> Verifying pymdownx.toc installation..."
+	$(POETRY_RUN) python3 -c "import pymdownx.toc" || echo "pymdownx.toc not found. Please run 'make install'."

README 2.md

@@ -0,0 +1,19 @@
+# Project Name
+
+A short paragraph describing what this app does and who it's for. Replace this text with a clear, one- or two-sentence summary.
+
+## Features
+- Briefly list core features of the app
+- Example: "Track tasks and reminders"
+- Example: "Syncs with iCloud"
+
+## Requirements
+- iOS/iPadOS/macOS/watchOS/visionOS: Replace with supported OS and minimum version
+- Xcode 15 or later (update as appropriate)
+- Swift 5.9 or later (update as appropriate)
+
+## Getting Started
+1. Clone the repository:
+   ```bash
+   git clone <your-repo-url>.git
+   cd <repo-folder>