cd-docs.yml

name: Documentation

on:
  push:
    branches: [main]
    paths:
      - 'docs/**'
      - 'artifacts/**/*.ttl'
      - 'artifacts/**/*.context.jsonld'
      - 'mkdocs.yml'
      - '.github/workflows/cd-docs.yml'

  # 1. Allows manual runs (use to republish w3id artifacts from a specific tag)
  workflow_dispatch:
    inputs:
      ref:
        description: "Git ref to checkout (tag, branch, or SHA). Leave empty for default branch."
        required: false
        type: string
        default: ''
      build_w3id:
        description: "Build versioned W3ID artifacts (only true for releases)"
        required: false
        type: boolean
        default: false

  # 2. Allows being called from release workflow
  workflow_call:
    inputs:
      ref:
        description: "The branch, tag or SHA to checkout (optional)"
        required: false
        type: string
        default: ''
      build_w3id:
        description: "Build versioned W3ID artifacts (only true for releases)"
        required: false
        type: boolean
        default: false

# Sets permissions of the GITHUB_TOKEN
permissions:
  contents: write   # Required to persist W3ID artifacts to w3id-content branch
  pages: write
  id-token: write

# Allow only one concurrent deployment
concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  build:
    name: 🔨 Build Documentation
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
          # Updated: Use the input ref if provided (e.g., 'main'),
          # otherwise default to the current context (tag or branch)
          ref: ${{ inputs.ref }}

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"
          cache: 'pip'

      - name: Install dependencies
        # Updated to use the [docs] extra from pyproject.toml
        run: python3 -m pip install -e ".[docs]"

      - name: Generate ontology documentation
        run: |
          # Generate PROPERTIES.md files
          python3 -m src.tools.utils.properties_updater
          # Generate class pages with WebVOWL embeds
          python3 -m src.tools.utils.class_page_generator

      - name: Setup Pages
        uses: actions/configure-pages@v4

      - name: Build MkDocs site
        run: |
          if [ -f mkdocs.yml ]; then
            mkdocs build --strict --site-dir site
          else
            echo "No mkdocs.yml found, using docs/ directory directly"
            mkdir -p site
            cp -r docs/* site/
          fi
          touch site/.nojekyll

      - name: Build W3ID artifacts
        if: ${{ inputs.build_w3id }}
        run: |
          python3 - <<'PY'
          from __future__ import annotations

          import shutil
          from pathlib import Path
          from urllib.parse import urlparse

          import rdflib
          from rdflib.namespace import RDF, OWL

          ROOT = Path(".").resolve()
          ARTIFACTS_DIR = ROOT / "artifacts"
          SITE_DIR = ROOT / "site"
          W3ID_DIR = SITE_DIR / "w3id"

          W3ID_DIR.mkdir(parents=True, exist_ok=True)

          def w3id_path(version_iri: str) -> str | None:
            parsed = urlparse(version_iri)
            if parsed.netloc != "w3id.org":
              return None
            path = parsed.path.lstrip("/").rstrip("/")
            if path.startswith("gaia-x4plcaad/ontologies/"):
              return path
            if path.startswith("ascs-ev/envited-x/"):
              return path
            return None

          def parse_version_iri(owl_path: Path) -> str | None:
            g = rdflib.Graph()
            g.parse(owl_path)
            ontology = next(g.subjects(RDF.type, OWL.Ontology), None)
            if ontology is None:
              return None
            version_iri = g.value(ontology, OWL.versionIRI) or ontology
            return str(version_iri)

          def merge_shacl(shacl_files: list[Path], output_path: Path) -> None:
            g = rdflib.Graph()
            for file_path in shacl_files:
              g.parse(file_path)
            g.serialize(destination=output_path, format="turtle")

          for owl_path in sorted(ARTIFACTS_DIR.glob("*/*.owl.ttl")):
            version_iri = parse_version_iri(owl_path)
            if not version_iri:
              continue

            path = w3id_path(version_iri)
            if not path:
              continue

            version_dir = W3ID_DIR / path
            version_dir.mkdir(parents=True, exist_ok=True)

            shutil.copy2(owl_path, version_dir / "ontology.ttl")

            shacl_files = sorted(owl_path.parent.glob("*.shacl.ttl"))
            if shacl_files:
              merge_shacl(shacl_files, version_dir / "shapes.ttl")

            context_files = sorted(owl_path.parent.glob("*.context.jsonld"))
            if context_files:
              shutil.copy2(context_files[0], version_dir / "context.jsonld")

            latest_dir = version_dir.parent / "latest"
            latest_dir.mkdir(parents=True, exist_ok=True)

            shutil.copy2(version_dir / "ontology.ttl", latest_dir / "ontology.ttl")
            if (version_dir / "shapes.ttl").exists():
              shutil.copy2(version_dir / "shapes.ttl", latest_dir / "shapes.ttl")
            if (version_dir / "context.jsonld").exists():
              shutil.copy2(version_dir / "context.jsonld", latest_dir / "context.jsonld")
          PY

      - name: Fetch cached W3ID artifacts
        uses: actions/checkout@v4
        with:
          ref: w3id-content
          path: w3id-cache
          fetch-depth: 1
        continue-on-error: true

      - name: Preserve W3ID artifacts
        run: |
          # Merge cached W3ID artifacts into the site.
          # Previously-published versions that are NOT in the fresh build
          # are preserved; freshly-built versions take precedence.
          if [ -d w3id-cache ] && [ ! -f w3id-cache/.empty ]; then
            find w3id-cache -type f -not -path '*/\.git/*' | while read -r src; do
              rel="${src#w3id-cache/}"
              dest="site/w3id/$rel"
              if [ ! -f "$dest" ]; then
                mkdir -p "$(dirname "$dest")"
                cp -a "$src" "$dest"
              fi
            done
          fi

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./site

      - name: Persist W3ID artifacts to cache branch
        run: |
          # Push the merged W3ID directory to the w3id-content branch so
          # future deploys can restore all previously-released versions.
          if [ ! -d site/w3id ] || [ -z "$(find site/w3id -type f -print -quit 2>/dev/null)" ]; then
            echo "No W3ID artifacts to persist — skipping."
            exit 0
          fi
          TMPDIR=$(mktemp -d)
          cp -r site/w3id/* "$TMPDIR/"
          cd "$TMPDIR"
          git init -b w3id-content
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add .
          git commit -m "chore: update W3ID artifacts cache [skip ci]"
          git remote add origin \
            "https://x-access-token:${{ github.token }}@github.com/${{ github.repository }}.git"
          git push --force origin w3id-content
          rm -rf "$TMPDIR"

  deploy:
    name: 🚀 Deploy to GitHub Pages
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4