Merge pull request #44 from GNS-Science/doc-default-group

- include doc in default groups when building docs, remove uv sync
- test build docs

Author: chrisdicaprio

.github/workflows/python-deploy-docs-test-uv.yml

@@ -0,0 +1,23 @@
+# A workflow that runs on push/PR to check that python-deploy-docs-uv.yml works
+
+name: python-deploy-docs-uv test workflow
+
+on:
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+  # schedules this to run weekly
+  # schedule:
+  #   - cron: '5 3 * * 0' # At 03:05 on Sunday
+  push:
+    branches: [main, pre-release]
+  pull_request:
+    branches: [main, pre-release]
+
+jobs:
+  call-test-workflow:
+    uses: ./.github/workflows/python-deploy-docs-uv.yml
+    with:
+      python-version: "3.12"
+      working-directory: samplePythonProjectUv
+      build-only: true
+    secrets: inherit

.github/workflows/python-deploy-docs-test.yml

@@ -0,0 +1,23 @@
+# A workflow that is scheduled to run regularly in order to check that python-deploy-docs.yml works
+
+name: python-deploy-docs test workflow
+
+on:
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+  # schedules this to run weekly
+  # schedule:
+  #   - cron: '5 3 * * 0' # At 03:05 on Sunday
+  push:
+    branches: [main, pre-release]
+  pull_request:
+    branches: [main, pre-release]
+
+jobs:
+  call-test-workflow:
+    uses: ./.github/workflows/python-deploy-docs.yml
+    with:
+      python-version: "3.12"
+      working-directory: samplePythonProject
+      build-only: true
+    secrets: inherit

.github/workflows/python-deploy-docs-uv.yml

@@ -30,7 +30,12 @@ on:
           description: Which optional group or groups to install. Use comma delimiter for multiple groups e.g `dev,doc`.
           required: false
           type: string
-          default: dev
+          default: dev,doc
+        build-only:
+          description: If true, skip the upload and deploy steps (useful for testing the build without deploying to GitHub Pages).
+          required: false
+          type: boolean
+          default: false
 
 
 # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
@@ -47,9 +52,7 @@ concurrency:
 
 jobs:
   deploy:
-    environment:
-        name: github-pages
-        url: ${{ steps.deployment.outputs.page_url }}
+    environment: ${{ !inputs.build-only && 'github-pages' || '' }}
     runs-on: ubuntu-latest
     timeout-minutes: ${{ inputs.timeout-minutes }}
     defaults:
@@ -70,18 +73,16 @@ jobs:
 
         #----------------------------------------------
         # build documentation
-        #  - uv sync installs the project root by default; the composite action
-        #    uses --no-install-project, so sync here to bring it in before building
         #----------------------------------------------
       - name: build documentation
         run: |
-          uv sync
           uv run mkdocs build
 
         #----------------------------------------------
         # package and upload artifact for deployment to GitHub Pages
         #----------------------------------------------
       - name: Upload artifact
+        if: ${{ !inputs.build-only }}
         uses: actions/upload-pages-artifact@v4
         with:
           path: ${{ inputs.working-directory }}/site
@@ -91,5 +92,6 @@ jobs:
         # deploy page
         #----------------------------------------------
       - name: Deploy Docs to GitHub Pages
+        if: ${{ !inputs.build-only }}
         id: deployment
         uses: actions/deploy-pages@v4

.github/workflows/python-deploy-docs.yml

@@ -30,7 +30,12 @@ on:
           description: Which optional group or groups to install. Use comma delimiter for multiple groups e.g `dev,doc`.
           required: false
           type: string
-          default: dev
+          default: dev,doc
+        build-only:
+          description: If true, skip the upload and deploy steps (useful for testing the build without deploying to GitHub Pages).
+          required: false
+          type: boolean
+          default: false
 
 
 # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
@@ -47,9 +52,7 @@ concurrency:
 
 jobs:
   deploy:
-    environment:
-        name: github-pages
-        url: ${{ steps.deployment.outputs.page_url }}
+    environment: ${{ !inputs.build-only && 'github-pages' || '' }}
     runs-on: ubuntu-latest
     timeout-minutes: ${{ inputs.timeout-minutes }}
     defaults:
@@ -78,9 +81,10 @@ jobs:
           poetry run mkdocs build
           
         #----------------------------------------------
-        # package and upload artifact for deployment to GitHub Pages 
+        # package and upload artifact for deployment to GitHub Pages
         #----------------------------------------------
       - name: Upload artifact
+        if: ${{ !inputs.build-only }}
         uses: actions/upload-pages-artifact@v4
         with:
           path: ${{ inputs.working-directory }}/site
@@ -90,5 +94,6 @@ jobs:
         # deploy page
         #----------------------------------------------
       - name: Deploy Docs to GitHub Pages
+        if: ${{ !inputs.build-only }}
         id: deployment
         uses: actions/deploy-pages@v4

samplePythonProject/docs/index.md

@@ -0,0 +1,3 @@
+# theproject
+
+Sample project documentation.

samplePythonProject/mkdocs.yml

@@ -0,0 +1,2 @@
+site_name: theproject
+docs_dir: docs