Merge pull request #9 from VectorInstitute/create_schema

Create schema, add script to convert README to docs md

Author: amrit110

.github/workflows/sync_readme.yml

@@ -0,0 +1,92 @@
+name: sync-readme
+permissions:
+  contents: write
+  pull-requests: write
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'README.md'
+      - 'scripts/sync_readme_to_docs.py'
+      - '.github/workflows/sync_readme.yml'
+  pull_request:
+    branches:
+      - main
+    paths:
+      - 'README.md'
+      - 'scripts/sync_readme_to_docs.py'
+      - '.github/workflows/sync_readme.yml'
+  workflow_dispatch:  # Allow manual triggering
+
+jobs:
+  sync-readme:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/[email protected]
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "0.6.13"
+          enable-cache: true
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install dependencies
+        run: uv sync --dev --group docs
+
+      - name: Run sync script
+        run: python scripts/sync_readme_to_docs.py
+
+      - name: Check for changes
+        id: git-check
+        run: |
+          git diff --quiet docs/index.md || echo "changes=true" >> $GITHUB_OUTPUT
+
+      - name: Setup Git
+        if: steps.git-check.outputs.changes == 'true' && github.event_name == 'push'
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+
+      - name: Commit changes
+        if: steps.git-check.outputs.changes == 'true' && github.event_name == 'push'
+        run: |
+          git add docs/index.md
+          git commit -m "docs: sync README.md reference implementations to docs/index.md
+
+          Automated update triggered by changes to README.md
+
+          [skip ci]"
+          git push
+
+      - name: Comment on PR
+        if: steps.git-check.outputs.changes == 'true' && github.event_name == 'pull_request'
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: '✅ The reference implementations table has been updated in the PR preview. Changes will be automatically committed to docs/index.md when merged.'
+            })
+
+      - name: Build docs for preview
+        if: github.event_name == 'pull_request'
+        run: uv run mkdocs build --clean
+
+      - name: Upload preview artifact
+        if: github.event_name == 'pull_request'
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs-preview
+          path: site/
+          retention-days: 1

.typos.toml

@@ -9,3 +9,4 @@ extend-ignore-re = [
 Tak = "Tak"
 Yau = "Yau"
 DOTA = "DOTA"
+EHR = "EHR"

CONTRIBUTING.md

@@ -4,22 +4,43 @@ Thank you for your interest in contributing to the Vector Institute Reference Im
 
 ## Adding a New Implementation
 
-If you are a Vector researcher or engineer and would like to add your implementation to this catalog, please follow these steps:
+The catalog is automatically synchronized between the README.md and the documentation site. If you are a Vector researcher or engineer and would like to add your implementation to this catalog, please follow these steps:
 
-1. Create a new entry in the appropriate year section of the `docs/index.md` file, following the existing format.
+1. **Add your implementation to the table in README.md** following the existing format
 2. Make sure to include:
    - Repository link
    - Short description
    - Tags for relevant technologies/algorithms
    - Information about datasets used
+   - Year of publication
+
+The documentation site (docs/index.md) will be automatically updated when your changes to README.md are merged.
+
+## Automatic Synchronization
+
+When you update README.md, a GitHub Actions workflow (`sync-readme.yml`) automatically:
+
+1. Extracts the reference implementation table from README.md
+2. Updates the cards in docs/index.md to match
+3. Commits the changes to the repository
+
+This ensures the documentation website always stays in sync with the README.md content.
+
+## Manual Synchronization
+
+If needed, you can manually run the synchronization script:
+
+```bash
+python scripts/sync_readme_to_docs.py
+```
 
 ## Submitting Changes
 
 To submit changes to this catalog:
 
 1. Fork the repository
 2. Create a feature branch
-3. Make your changes
+3. Make your changes to README.md
 4. Submit a pull request
 
 When submitting a PR, please fill out the PR template. If the PR fixes an issue, don't forget to link the PR to the issue!
@@ -32,6 +53,20 @@ We have templates available for:
 
 Please use these templates when opening new issues to ensure all necessary information is provided.
 
+## Building Documentation Locally
+
+To build and preview the documentation locally:
+
+```bash
+# Install dependencies using uv
+uv sync --group docs
+
+# Serve the documentation
+uv run mkdocs serve
+```
+
+Then visit http://localhost:8000 in your browser.
+
 ## Additional Information
 
 For questions about contributing to the Reference Implementation Catalog, please reach out to the AI Engineering team at Vector Institute.