Merge main

.github/workflows/ci.yml

@@ -1,47 +1,75 @@
-name: Run Tests
+name: "Run Tests"
 
-on: [push, pull_request]
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    types:
+      - opened
+      - synchronize
+      - reopened
+      - closed
 
 jobs:
   test:
     runs-on: ubuntu-latest
 
     steps:
-    - name: Checkout code
-      uses: actions/checkout@v4
-
-    - name: Set up Python
-      uses: actions/setup-python@v5
-      with:
-        python-version: 3.11
-
-    - name: Install Poetry
-      run: |
-        python -m pip install --upgrade pip
-        python -m pip install poetry
-
-    - name: Install dependencies
-      working-directory: ./space2stats_api/src
-      run: |
-        poetry install --with test
-
-    - name: install lib postgres
-      uses: nyurik/action-setup-postgis@v2
-
-    - name: Run pre-commit
-      working-directory: ./space2stats_api/src
-      run: |
-        poetry run pre-commit run --all-files
-
-    - name: Run tests
-      working-directory: ./space2stats_api/src
-      run: |
-        poetry run python -m pytest --benchmark-skip tests
-      env:
-        PGHOST: localhost
-        PGPORT: 5432
-        PGDATABASE: mydatabase
-        PGUSER: myuser
-        PGPASSWORD: mypassword
-        PGTABLENAME: space2stats
-        S3_BUCKET_NAME: test-bucket
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.11
+
+      - name: Install Poetry
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install poetry
+
+      - name: Install dependencies
+        working-directory: ./space2stats_api/src
+        run: |
+          poetry install --with test
+
+      - name: install lib postgres
+        uses: nyurik/action-setup-postgis@v2
+
+      - name: Run pre-commit
+        working-directory: ./space2stats_api/src
+        run: |
+          poetry run pre-commit run --all-files
+
+      - name: Run tests
+        working-directory: ./space2stats_api/src
+        run: |
+          poetry run python -m pytest --benchmark-skip tests
+        env:
+          PGHOST: localhost
+          PGPORT: 5432
+          PGDATABASE: mydatabase
+          PGUSER: myuser
+          PGPASSWORD: mypassword
+          PGTABLENAME: space2stats
+          S3_BUCKET_NAME: test-bucket
+
+  deploy-to-dev:
+    if: ${{ github.event_name == 'pull_request' }}
+    needs: test
+    uses: "./.github/workflows/reusable-deploy.yml"
+    with:
+      environment: Space2Stats API Dev
+      stage: pr-${{ github.event.pull_request.number }}
+      pr-number: ${{ github.event.pull_request.number }}
+    secrets: inherit
+
+  deploy-to-production:
+    if: ${{ github.event_name == 'push' && github.ref_name == 'main' }}
+    needs: test
+    uses: "./.github/workflows/reusable-deploy.yml"
+    with:
+      environment: Space2Stats API Prod
+      stage: prod
+    secrets: inherit

.github/workflows/destroy.yml

@@ -0,0 +1,70 @@
+name: Destroy Preview Environment
+
+on:
+  pull_request:
+    types:
+      - closed
+
+permissions:
+  id-token: write
+  contents: read
+  pull-requests: write
+
+jobs:
+  destroy:
+    concurrency: Space2Stats API Dev
+    environment: Space2Stats API Dev
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository code
+        uses: actions/checkout@v2
+
+      - name: Install AWS CDK
+        run: npm install -g aws-cdk
+
+      - name: Configure AWS credentials
+        uses: aws-actions/configure-aws-credentials@v4
+        with:
+          role-to-assume: arn:aws:iam::017820688988:role/Space2Stats-Deploy-Role
+          aws-region: ${{ vars.CDK_DEFAULT_REGION }}
+
+      - name: Install CDK dependencies
+        working-directory: ./space2stats_api/cdk
+        run: |
+          pip install -r requirements-cdk.txt
+
+      - name: Tear down CDK stack
+        working-directory: ./space2stats_api/cdk
+        env:
+          STAGE: pr-${{ github.event.pull_request.number }}
+          PGHOST: ${{ secrets.PGHOST }}
+          PGPORT: ${{ secrets.PGPORT }}
+          PGDATABASE: ${{ secrets.PGDATABASE }}
+          PGUSER: ${{ secrets.PGUSER }}
+          PGPASSWORD: ${{ secrets.PGPASSWORD }}
+          PGTABLENAME: ${{ secrets.PGTABLENAME }}
+          CDK_CERTIFICATE_ARN: ${{ vars.CDK_CERTIFICATE_ARN }}
+          CDK_DEFAULT_ACCOUNT: ${{ vars.CDK_DEFAULT_ACCOUNT }}
+          CDK_DEFAULT_REGION: ${{ vars.CDK_DEFAULT_REGION }}
+          CDK_DOMAIN_NAME: ${{ vars.CDK_DOMAIN_NAME }}
+        run: cdk destroy --require-approval never
+
+      - name: Find Comment
+        uses: peter-evans/find-comment@v3
+        id: find-comment
+        if: ${{ github.event.pull_request.number }}
+        with:
+          issue-number: ${{ github.event.pull_request.number }}
+          comment-author: "github-actions[bot]"
+          body-includes: "PR Deployment Details:"
+
+      - name: Create or update comment with removal confirmation
+        uses: peter-evans/create-or-update-comment@v4
+        if: ${{ github.event.pull_request.number }}
+        with:
+          issue-number: ${{ github.event.pull_request.number }}
+          comment-id: ${{ steps.find-comment.outputs.comment-id }}
+          body: |
+            Removed PR Preview Environment.
+          edit-mode: append

.github/workflows/reusable-deploy.yml

@@ -0,0 +1,85 @@
+name: Deploy
+
+on:
+  workflow_call:
+    inputs:
+      environment:
+        type: string
+        required: true
+      stage:
+        type: string
+        required: true
+      pr-number:
+        type: number
+        required: false
+
+permissions:
+  id-token: write
+  contents: read
+  pull-requests: write
+
+jobs:
+  deploy:
+    concurrency: ${{ inputs.stage }}
+    environment: ${{ inputs.environment }}
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository code
+        uses: actions/checkout@v2
+
+      - name: Install AWS CDK
+        run: npm install -g aws-cdk
+
+      - name: Configure AWS credentials
+        uses: aws-actions/configure-aws-credentials@v4
+        with:
+          role-to-assume: arn:aws:iam::017820688988:role/Space2Stats-Deploy-Role
+          aws-region: ${{ vars.CDK_DEFAULT_REGION }}
+
+      - name: Install CDK dependencies
+        working-directory: ./space2stats_api/cdk
+        run: |
+          pip install -r requirements-cdk.txt
+
+      - name: Deploy CDK stack to staging
+        working-directory: ./space2stats_api/cdk
+        env:
+          STAGE: ${{ inputs.stage }}
+          PGHOST: ${{ secrets.PGHOST }}
+          PGPORT: ${{ secrets.PGPORT }}
+          PGDATABASE: ${{ secrets.PGDATABASE }}
+          PGUSER: ${{ secrets.PGUSER }}
+          PGPASSWORD: ${{ secrets.PGPASSWORD }}
+          PGTABLENAME: ${{ secrets.PGTABLENAME }}
+          CDK_CERTIFICATE_ARN: ${{ vars.CDK_CERTIFICATE_ARN }}
+          CDK_DEFAULT_ACCOUNT: ${{ vars.CDK_DEFAULT_ACCOUNT }}
+          CDK_DEFAULT_REGION: ${{ vars.CDK_DEFAULT_REGION }}
+          CDK_DOMAIN_NAME: ${{ vars.CDK_DOMAIN_NAME }}
+        run: cdk deploy --require-approval never --outputs-file outputs.json
+
+      - name: Get API URL
+        id: get-api-url
+        working-directory: ./space2stats_api/cdk
+        run: |
+          echo "api-url=$(jq -r '."Space2Stats-${{ inputs.stage }}".ApiGatewayUrl' outputs.json)" >> $GITHUB_OUTPUT
+
+      - name: Find Comment
+        uses: peter-evans/find-comment@v3
+        id: find-comment
+        if: ${{ inputs.pr-number }}
+        with:
+          issue-number: ${{ inputs.pr-number }}
+          comment-author: "github-actions[bot]"
+          body-includes: "PR Deployment Details:"
+
+      - name: Create or update comment with URL
+        uses: peter-evans/create-or-update-comment@v4
+        if: ${{ inputs.pr-number }}
+        with:
+          issue-number: ${{ inputs.pr-number }}
+          comment-id: ${{ steps.find-comment.outputs.comment-id }}
+          body: |
+            PR Deployment Details:
+            🚀 PR deployed to ${{ steps.get-api-url.outputs.api-url }}
+          edit-mode: replace

docs/_config.yml

@@ -35,3 +35,8 @@ sphinx:
   config:
     html_show_copyright: false
     html_last_updated_fmt: "%b %d, %Y"
+    apidoc_module_dir: ../space2stats_api/src
+  extra_extensions:
+  - 'sphinx.ext.autodoc'
+  - sphinx.ext.napoleon
+  - sphinxcontrib.apidoc

docs/_toc.yml

@@ -1,21 +1,26 @@
 format: jb-book
-root: README
+root: docs/readme.md
 
 parts:
   - caption: Concept Note
     numbered: False
     chapters:
-      - file: docs/Introduction.md    
-  - caption: Example summaries
+      - file: docs/Introduction.md
+      - file: docs/annexA.md    
+  - caption: S2S Sub-tasks
     numbered: False
     chapters:
-        - file: notebooks/Space2Stats_Comparing_H3_WBAdmin.ipynb
-        - file: notebooks/Space2Stats_RunZonal.ipynb
-        - file: notebooks/Space2Stats_RunZonal_HTI.ipynb
-  - caption: Food Security
+        - file: docs/sub_tasks/admin_bounds.md
+        - file: docs/sub_tasks/sub_national_poverty.md
+        - file: docs/sub_tasks/geest.md
+        - file: docs/sub_tasks/geo_enhancement.md
+  - caption: S2S Examples
     numbered: False
     chapters:
-        - file: notebooks/h3-food-security.ipynb
-  - caption: Additional Resources
+        - file: notebooks/user-docs/space2stats_py_package_demo.ipynb
+        - file: notebooks/user-docs/space2stats_api_demo.ipynb
+        - file: notebooks/user-docs/space2stats_api_demo_R.Rmd
+  - caption: S2S Python Documentation
+    numbered: False
     chapters:
-      - file: docs/annexA.md
+        - file: docs/api.rst

docs/annexA.md

@@ -1,4 +1,4 @@
-# Annex A: Datasets to be Summarized
+# Annex A: S2S Datasets
 |Phase|Category|Variable Name|Source|
 |:----|:----|:----|:----|
 |1|Access|Distance to airport  |Global Friction Surface 2019|