Standardize CI/docs to Harmoniqs known-good layout

.github/workflows/CI.yml

@@ -1,28 +1,48 @@
 name: CI
 on:
   push:
-    branches: [main]
+    branches:
+      - main
     tags: ['*']
   pull_request:
-permissions:
-  contents: read
+  workflow_dispatch:
 concurrency:
+  # Skip intermediate builds: always.
+  # Cancel intermediate builds: only if it is a pull request build.
   group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
+  cancel-in-progress: ${{ startsWith(github.ref, 'refs/pull/') }}
 jobs:
   test:
-    name: Julia ${{ matrix.version }} - ${{ matrix.os }}
+    name: Julia ${{ matrix.version }} - ${{ matrix.os }} - ${{ matrix.arch }} - ${{ github.event_name }}
     runs-on: ${{ matrix.os }}
+    timeout-minutes: 60
+    permissions: # needed to allow julia-actions/cache to proactively delete old caches that it has created
+      actions: write
+      contents: read
     strategy:
       fail-fast: false
       matrix:
-        version: ['1.10', '1.11']
-        os: [ubuntu-latest]
+        version:
+          - '1.12'
+          - '1.11'
+          - '1.10'
+        os:
+          - ubuntu-latest
+        arch:
+          - x64
+          # - x86
     steps:
-      - uses: actions/checkout@v4
-      - uses: julia-actions/setup-julia@v2
+      - uses: actions/checkout@v7
+      - uses: julia-actions/setup-julia@v3
         with:
           version: ${{ matrix.version }}
-      - uses: julia-actions/cache@v2
+          arch: ${{ matrix.arch }}
+      - uses: julia-actions/cache@v3
       - uses: julia-actions/julia-buildpkg@v1
       - uses: julia-actions/julia-runtest@v1
+      - uses: julia-actions/julia-processcoverage@v1
+      - uses: codecov/codecov-action@v7
+        with:
+          files: lcov.info
+          token: ${{ secrets.CODECOV_TOKEN }}
+          fail_ci_if_error: false

.github/workflows/CompatHelper.yml

@@ -0,0 +1,18 @@
+name: CompatHelper
+on:
+  schedule:
+    - cron: 0 0 * * *
+  workflow_dispatch:
+permissions:
+  contents: read
+jobs:
+  CompatHelper:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Pkg.add("CompatHelper")
+        run: julia -e 'using Pkg; Pkg.add("CompatHelper")'
+      - name: CompatHelper.main()
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          COMPATHELPER_PRIV: ${{ secrets.DOCUMENTER_KEY }}
+        run: julia -e 'using CompatHelper; CompatHelper.main()'

.github/workflows/Formatter.yml

@@ -0,0 +1,43 @@
+name: Formatter
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+permissions:
+  contents: read
+jobs:
+  julia-format:
+    name: Formatter
+    runs-on: ubuntu-latest
+    steps:
+      - uses: julia-actions/setup-julia@latest
+      - uses: actions/checkout@v6
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+      - name: Install JuliaFormatter and format
+        run: |
+          julia --color=yes -e 'using Pkg; Pkg.add(PackageSpec(name="JuliaFormatter"))'
+          julia --color=yes -e 'using JuliaFormatter; format(".", verbose=true)'
+      - name: Commit formatted code
+        if: github.event_name == 'workflow_dispatch'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git diff --quiet && exit 0
+          git add -A
+          git commit -m "chore: autoformat"
+          git push
+      - name: Format check
+        if: github.event_name != 'workflow_dispatch'
+        run: |
+          julia --color=yes -e '
+          out = Cmd(`git diff --name-only`) |> read |> String
+          if out == ""
+            exit(0)
+          else
+            @error "Some files have not been formatted !!!"
+            write(stdout, out)
+            exit(1)
+          end'

.github/workflows/docs.yml

@@ -0,0 +1,75 @@
+name: Documentation
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+    tags: ["*"]
+
+  repository_dispatch:
+    types: [tagbot-release-created]
+
+concurrency:
+  # Skip intermediate builds: always.
+  # Cancel intermediate builds: only if it is a pull request build.
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ startsWith(github.ref, 'refs/pull/') }}
+jobs:
+  docs:
+    name: Documentation
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    permissions:
+      contents: write
+      statuses: write
+    env:
+      DOC_TEMPLATE_VERSION: "v0.7.0" # Change this to the specific tag version you want
+    steps:
+      - uses: actions/checkout@v7
+      - uses: julia-actions/setup-julia@v3
+      - uses: julia-actions/cache@v3
+      - name: Use Documentation Template
+        run: |
+          ./docs/get_docs_utils.sh ${{ env.DOC_TEMPLATE_VERSION }}
+      - uses: julia-actions/julia-buildpkg@v1
+      - uses: julia-actions/julia-docdeploy@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - name: Upload documentation artifacts
+        uses: actions/upload-artifact@v6
+        with:
+          name: documentation-build
+          path: docs/build/
+          retention-days: 1
+      - run: |
+          julia --project=docs -e '
+            using Documenter: DocMeta, doctest
+            using Intonato
+            DocMeta.setdocmeta!(Intonato, :DocTestSetup, :(using Intonato); recursive=true)
+            doctest(Intonato)'
+
+  tagbot-dispatch:
+    name: Dispatch on TagBot Release
+    runs-on: ubuntu-latest
+    needs: docs
+    if: github.event_name == 'repository_dispatch'
+    steps:
+      - name: Dispatch PiccoloMultiDocs workflow
+        uses: peter-evans/repository-dispatch@v4
+        with:
+          token: ${{ secrets.REPO_ACCESS_TOKEN }}
+          repository: harmoniqs/PiccoloMultiDocs.jl
+          event-type: rebuild-docs
+
+  tag-push-dispatch:
+    name: Dispatch on Tag Push
+    runs-on: ubuntu-latest
+    needs: docs
+    if: github.ref_type == 'tag'
+    steps:
+      - name: Dispatch PiccoloMultiDocs workflow
+        uses: peter-evans/repository-dispatch@v4
+        with:
+          token: ${{ secrets.REPO_ACCESS_TOKEN }}
+          repository: harmoniqs/PiccoloMultiDocs.jl
+          event-type: rebuild-docs

.github/workflows/nightly.yml

@@ -0,0 +1,34 @@
+name: Nightly
+on:
+  schedule:
+    - cron: '00 00 * * *'
+  workflow_dispatch:
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ startsWith(github.ref, 'refs/pull/') }}
+jobs:
+  test:
+    name: Julia nightly - ${{ matrix.os }} - ${{ matrix.arch }} - ${{ github.event_name }}
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 60
+    permissions:
+      actions: write
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        version:
+          - 'pre'
+        os:
+          - ubuntu-latest
+        arch:
+          - x64
+    steps:
+      - uses: actions/checkout@v7
+      - uses: julia-actions/setup-julia@v3
+        with:
+          version: ${{ matrix.version }}
+          arch: ${{ matrix.arch }}
+      - uses: julia-actions/cache@v3
+      - uses: julia-actions/julia-buildpkg@v1
+      - uses: julia-actions/julia-runtest@v1

.gitignore

@@ -1,4 +1,59 @@
+# Files generated by invoking Julia with --code-coverage
+*.jl.cov
+*.jl.*.cov
+
+# Files generated by invoking Julia with --track-allocation
+*.jl.mem
+
+# System-specific files and directories generated by the BinaryProvider and BinDeps packages
+# They contain absolute paths specific to the host computer, and so should not be committed
+deps/deps.jl
+deps/build.log
+deps/downloads/
+deps/usr/
+deps/src/
+
+# Build artifacts for creating documentation generated by the Documenter package
+docs/build/
+docs/site/
+docs/clones/
+docs/out/
+docs/src/generated/
+
+docs/src/assets/
+
+# Build artifact for using README as index (probably shouldn't have this checked into version control)
+docs/src/index.md
+
+# File generated by Pkg, the package manager, based on a corresponding Project.toml
+# It records a fixed state of all packages used by the project. As such, it should not be
+# committed for packages, but should be committed for applications that require a static
+# environment.
 Manifest.toml
+docs/Manifest.toml
+
+# Project specific ignores below
+# generated example artifacts
+/examples/**/plots/
+/examples/**/trajectories/
+
+# external pkgs and configs
+pardiso.lic
+/.CondaPkg/
+*.code-workspace
+
+# generated build folder
+build/
+
+# VS code
+.vscode/settings.json
+
+# doc_template stuff
+# Temporary directory for doc_template cloning
+doc_template_temp/
+
+# This file is updated via script
+docs/utils.jl
 
 # Agent working memory (not package content)
 .claude/

docs/Project.toml

@@ -0,0 +1,7 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+Intonato = "4c8581c7-0eaf-45eb-b8fa-a3474c50779c"
+Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
+LiveServer = "16fef848-5104-11e9-1b77-fb7a48bbb589"
+PiccoloDocsTemplate = "a90a139f-c522-4b23-980b-4210ddb8d065"
+Revise = "295af30f-e4ad-537b-8983-00126c2a3abe"

docs/get_docs_utils.sh

@@ -0,0 +1,38 @@
+#!/bin/bash
+
+set -euo pipefail
+
+# Get the directory where this script is located
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$SCRIPT_DIR/.."
+
+# if argument is provided, use it as the DOC_TEMPLATE_VERSION
+if [[ $# -gt 0 ]]; then
+    DOC_TEMPLATE_VERSION="$1"
+else
+    WORKFLOW_FILE="$PROJECT_ROOT/.github/workflows/docs.yml"
+
+    # Check if workflow file exists
+    if [[ ! -f "$WORKFLOW_FILE" ]]; then
+        echo "GitHub workflow file not found at: $WORKFLOW_FILE"
+        exit 1
+    fi
+
+    DOC_TEMPLATE_VERSION=$(grep -E '^\s*DOC_TEMPLATE_VERSION:' "$WORKFLOW_FILE" | sed -E 's/.*DOC_TEMPLATE_VERSION:\s*"([^"]+)".*/\1/')
+fi
+
+if [[ -z "$DOC_TEMPLATE_VERSION" ]]; then
+    echo "DOC_TEMPLATE_VERSION is not set"
+    echo "Please provide a version tag as an arg or ensure it is set in $WORKFLOW_FILE"
+    echo "Could not extract DOC_TEMPLATE_VERSION from $WORKFLOW_FILE"
+    echo "Expected format: DOC_TEMPLATE_VERSION: \"<version tag here>\""
+    exit 1
+fi
+
+# Clone the repository
+echo "Grabbing PiccoloDocsTemplate at version $DOC_TEMPLATE_VERSION"
+julia --project="$PROJECT_ROOT/docs" -e "
+using Pkg; Pkg.add(url=\"https://github.com/harmoniqs/PiccoloDocsTemplate.jl\", rev=\"$DOC_TEMPLATE_VERSION\")
+"
+
+echo "Successfully updated PiccoloDocsTemplate with version $DOC_TEMPLATE_VERSION"

docs/make.jl

@@ -0,0 +1,15 @@
+using Intonato
+using PiccoloDocsTemplate
+
+pages = ["Home" => "index.md", "Library" => "lib.md"]
+
+generate_docs(
+    @__DIR__,
+    "Intonato",
+    [Intonato],
+    pages;
+    make_literate = false,
+    make_assets = false,
+    format_kwargs = (canonical = "https://docs.harmoniqs.co/Intonato.jl",),
+    versions = ["dev" => "dev", "stable" => "v^", "v#.#"],
+)

docs/src/lib.md

@@ -0,0 +1,22 @@
+# API
+
+```@meta
+CollapsedDocStrings = true
+```
+
+The central entry point. `solve!(::PulseTuningProblem)` is defined as a
+`Piccolo.solve!` method (the function-name binding is owned by the `Piccolo` /
+`DirectTrajOpt` module, in scope here via Intonato's `@reexport using Piccolo`).
+It is documented explicitly so it is guaranteed to appear even if a future
+refactor changes which module owns the binding; the `@autodocs` block below is
+filtered to skip this method so it is not documented twice.
+
+```@docs
+solve!(::Intonato.PulseTuningProblem)
+```
+
+```@autodocs
+Modules = [Intonato]
+Order = [:type, :function]
+Filter = b -> b !== solve!
+```

src/Intonato.jl

@@ -49,7 +49,8 @@ include("problems/test.jl")
 # Types
 export Measurement, MeasurementModel
 export AbstractExperiment, SimulatedExperiment, HardwareExperiment
-export AbstractMeasurement, DeterministicMeasurement, ShotNoiseMeasurement, KnownCovarianceMeasurement
+export AbstractMeasurement,
+    DeterministicMeasurement, ShotNoiseMeasurement, KnownCovarianceMeasurement
 export pauli_covariance, population_covariance, wigner_covariance
 export pauli, pop
 export AbstractHardwareBackend
@@ -81,7 +82,8 @@ export AbstractDeviceModel, NominalModel, predict, adapt!
 # IdentityStrategy stand-in. Concrete tuning strategies plug in via this
 # interface.
 export AbstractPulseTuningProblem, AbstractTuningStrategy, IdentityStrategy, step
-export prepare_strategy, tuning_goal, candidate_trajectory, last_timings, accepts_global_data
+export prepare_strategy,
+    tuning_goal, candidate_trajectory, last_timings, accepts_global_data
 
 # Closed-loop tuning chassis. The chassis is strategy-generic; its
 # result/record types are public.