feat: versioned docs (#414)

(Finally) sets up versioned docs with a version selector. 

we deploy on every push to `main` on the `main` tag, and on every
release on the tag of that release + update `latest`

this finally fixes the issue we were having around missing schema files.

tested it on a fork. :) 

Todo
- [x] update schema url in default config 
- [x] Before merging: delete gh-pages branch 

closes #312
fixes #319

Author: psteinroe

.github/workflows/deploy_docs.yml

@@ -1,9 +1,11 @@
 name: Build and Deploy Documentation
 
 on:
+  push:
+    branches:
+      - main
   release:
-    types: [released]
-  workflow_dispatch:
+    types: [published]
 
 permissions:
   contents: write
@@ -13,25 +15,34 @@ permissions:
 jobs:
   build:
     runs-on: ubuntu-latest
-
     steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
+      - uses: actions/checkout@v4
         with:
           fetch-depth: 0
 
       - name: Install uv
         uses: astral-sh/setup-uv@v5
         with:
-            enable-cache: true
+          enable-cache: true
 
       - name: Set up Python
         run: uv python install
 
       - name: Install the project
         run: uv sync --all-extras --dev
 
-      - run: uv run mkdocs gh-deploy --force
+      - name: Configure Git
+        run: |
+          git config user.name 'github-actions[bot]'
+          git config user.email 'github-actions[bot]@users.noreply.github.com'
+
+      - name: Build Docs Website
+        run: |
+          if [ "${{ github.event_name }}" = "release" ]; then
+            uv run mike deploy --push --update-aliases ${{ github.event.release.tag_name }} latest
+          else
+            uv run mike deploy --push main
+          fi
 
   deploy:
     needs: build
@@ -44,12 +55,16 @@ jobs:
         uses: actions/checkout@v4
         with:
           ref: gh-pages
+
       - name: Setup Pages
         uses: actions/configure-pages@v5
+
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
         with:
           path: '.'
+
       - name: Deploy to GitHub Pages
         id: deployment
         uses: actions/deploy-pages@v4
+

crates/pgt_workspace/src/configuration.rs

@@ -186,9 +186,9 @@ pub fn create_config(
         configuration.schema = node_schema_path.to_str().map(String::from);
     } else if VERSION == "0.0.0" {
         // VERSION is 0.0.0 if it has not been explicitly set (e.g local dev, as fallback)
-        configuration.schema = Some("https://pgtools.dev/schemas/latest/schema.json".to_string());
+        configuration.schema = Some("https://pgtools.dev/latest/schema.json".to_string());
     } else {
-        configuration.schema = Some(format!("https://pgtools.dev/schemas/{VERSION}/schema.json"));
+        configuration.schema = Some(format!("https://pgtools.dev/{VERSION}/schema.json"));
     }
 
     let contents = serde_json::to_string_pretty(&configuration)

docs/codegen/src/schema.rs

@@ -1,4 +1,4 @@
-use pgt_configuration::{PartialConfiguration, VERSION};
+use pgt_configuration::PartialConfiguration;
 use schemars::{
     schema::{RootSchema, Schema, SchemaObject},
     schema_for,
@@ -10,25 +10,10 @@ use std::{fs, path::Path};
 ///
 /// * `docs_dir`: Path to the docs directory.
 pub fn generate_schema(docs_dir: &Path) -> anyhow::Result<()> {
-    let schemas_dir = docs_dir.join("schemas");
-    let latest_schema_dir = schemas_dir.join("latest");
-    let latest_schema_path = latest_schema_dir.join("schema.json");
-
-    let version_schema_dir = schemas_dir.join(VERSION);
-    let version_schema_path = version_schema_dir.join("schema.json");
-
-    if !latest_schema_dir.exists() {
-        fs::create_dir_all(&latest_schema_dir)?;
-    }
-
-    if !version_schema_dir.exists() {
-        fs::create_dir_all(&version_schema_dir)?;
-    }
-
+    let schema_path = docs_dir.join("schema.json");
     let schema_content = get_configuration_schema_content()?;
 
-    fs::write(latest_schema_path, &schema_content)?;
-    fs::write(version_schema_path, &schema_content)?;
+    fs::write(schema_path, &schema_content)?;
 
     Ok(())
 }