docs.yml

name: Docs

# Build auto-generated documentation for all four owlmake interfaces and publish
# them to GitHub Pages as one site:
#   /cli     CLI reference   (generated from `owlmake __cli-spec`)
#   /rust    Rust API        (cargo doc)
#   /python  Python API      (pdoc, from the native extension's docstrings)
#   /js      JS/TS API       (TypeDoc, from the wasm-bindgen .d.ts)
#
# The doc sets come from three jobs that share no build and so run in parallel,
# each uploading its slice of the site; `assemble` merges the slices and adds the
# landing page, and `deploy` publishes the result to GitHub Pages (Source:
# "GitHub Actions"). Everything runs on every push to dev (the project's primary
# branch) and on manual `workflow_dispatch`.

on:
  push:
    branches: [dev]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: docs-${{ github.ref }}
  cancel-in-progress: true

jobs:
  cli-and-rust:
    name: cli + rust docs
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Rust toolchain
        uses: dtolnay/rust-toolchain@stable
        with:
          targets: wasm32-unknown-unknown

      - name: Cache cargo build
        uses: Swatinem/rust-cache@v2

      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: Install tools
        run: python -m pip install --upgrade pip markdown

      # --- CLI reference: generated from the binary's __cli-spec ---
      # Runs before the Rust docs because it is what creates `site/`.
      - name: CLI docs
        run: |
          cargo build --locked
          python scripts/gen_cli_docs.py
          python scripts/md_to_html.py docs/cli.md site/cli/index.html "owlmake CLI reference"

      # --- Rust API: cargo doc for the workspace crates ---
      - name: Rust docs
        run: |
          cargo doc --no-deps --workspace
          cp -r target/doc site/rust
          # `cargo doc --workspace` documents several crates and so emits no
          # top-level index.html; redirect /rust/ to the main crate's docs so the
          # Pages landing link resolves instead of 404ing.
          test -f site/rust/index.html || \
            printf '<!doctype html><meta http-equiv="refresh" content="0; url=owlmake/index.html">\n' \
              > site/rust/index.html

      - name: Upload slice
        uses: actions/upload-artifact@v4
        with:
          name: docs-cli-rust
          path: site

  python-docs:
    name: python docs
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Rust toolchain
        uses: dtolnay/rust-toolchain@stable

      - name: Cache cargo build
        uses: Swatinem/rust-cache@v2

      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: Install tools
        run: python -m pip install --upgrade pip maturin pdoc

      # --- Python API: pdoc over the installed native extension ---
      # The wheel is unoptimized: pdoc reads the extension's docstrings and never
      # runs an ontology through it, so the optimized build the shipped wheels get
      # (.github/workflows/wheels.yml) would buy nothing here but compile time.
      - name: Python docs
        run: |
          maturin build --out dist -m crates/owlmake-py/Cargo.toml
          python -m pip install --no-index --find-links dist owlmake
          pdoc -o site/python owlmake

      - name: Upload slice
        uses: actions/upload-artifact@v4
        with:
          name: docs-python
          path: site

  js-docs:
    name: js docs
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Rust toolchain
        uses: dtolnay/rust-toolchain@stable
        with:
          targets: wasm32-unknown-unknown

      - name: Cache cargo build
        uses: Swatinem/rust-cache@v2

      # A prebuilt wasm-pack, so the job spends its time on owlmake rather than
      # on compiling its build tool.
      - name: Install wasm-pack
        uses: taiki-e/install-action@v2
        with:
          tool: wasm-pack

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install tools
        run: npm install -g typedoc typescript

      # --- JS/TS API: TypeDoc over the wasm-bindgen .d.ts ---
      - name: JS docs
        working-directory: crates/owlmake-wasm
        run: |
          wasm-pack build --target nodejs --out-dir pkg
          typedoc --out "$GITHUB_WORKSPACE/site/js"

      - name: Upload slice
        uses: actions/upload-artifact@v4
        with:
          name: docs-js
          path: site

  assemble:
    name: assemble site
    needs: [cli-and-rust, python-docs, js-docs]
    runs-on: ubuntu-latest
    steps:
      # For docs/index.html, the landing page; the doc sets themselves arrive as
      # artifacts.
      - uses: actions/checkout@v4

      - name: Collect the slices
        uses: actions/download-artifact@v4
        with:
          pattern: docs-*
          merge-multiple: true
          path: site

      - name: Landing page
        run: cp docs/index.html site/index.html

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

  deploy:
    needs: assemble
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deploy.outputs.page_url }}
    steps:
      - id: deploy
        uses: actions/deploy-pages@v4