Skip to content

Commit ed26eec

Browse files
jack-champagnejack-champagne
authored
Standardize CI/docs to Harmoniqs known-good layout (#3)
Adds docs/ (Documenter + PiccoloDocsTemplate, with solve! documented), docs/CompatHelper/nightly/Formatter workflows, upgrades CI to 1.10/1.11/1.12 + coverage, least-privilege workflow tokens, and a JuliaFormatter pass. No source logic changes.
1 parent 34fbfde commit ed26eec

30 files changed

Lines changed: 565 additions & 168 deletions

‎.github/workflows/CI.yml‎

Lines changed: 30 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,28 +1,48 @@
11
name: CI
22
on:
33
push:
4-
branches: [main]
4+
branches:
5+
- main
56
tags: ['*']
67
pull_request:
7-
permissions:
8-
contents: read
8+
workflow_dispatch:
99
concurrency:
10+
# Skip intermediate builds: always.
11+
# Cancel intermediate builds: only if it is a pull request build.
1012
group: ${{ github.workflow }}-${{ github.ref }}
11-
cancel-in-progress: true
13+
cancel-in-progress: ${{ startsWith(github.ref, 'refs/pull/') }}
1214
jobs:
1315
test:
14-
name: Julia ${{ matrix.version }} - ${{ matrix.os }}
16+
name: Julia ${{ matrix.version }} - ${{ matrix.os }} - ${{ matrix.arch }} - ${{ github.event_name }}
1517
runs-on: ${{ matrix.os }}
18+
timeout-minutes: 60
19+
permissions: # needed to allow julia-actions/cache to proactively delete old caches that it has created
20+
actions: write
21+
contents: read
1622
strategy:
1723
fail-fast: false
1824
matrix:
19-
version: ['1.10', '1.11']
20-
os: [ubuntu-latest]
25+
version:
26+
- '1.12'
27+
- '1.11'
28+
- '1.10'
29+
os:
30+
- ubuntu-latest
31+
arch:
32+
- x64
33+
# - x86
2134
steps:
22-
- uses: actions/checkout@v4
23-
- uses: julia-actions/setup-julia@v2
35+
- uses: actions/checkout@v7
36+
- uses: julia-actions/setup-julia@v3
2437
with:
2538
version: ${{ matrix.version }}
26-
- uses: julia-actions/cache@v2
39+
arch: ${{ matrix.arch }}
40+
- uses: julia-actions/cache@v3
2741
- uses: julia-actions/julia-buildpkg@v1
2842
- uses: julia-actions/julia-runtest@v1
43+
- uses: julia-actions/julia-processcoverage@v1
44+
- uses: codecov/codecov-action@v7
45+
with:
46+
files: lcov.info
47+
token: ${{ secrets.CODECOV_TOKEN }}
48+
fail_ci_if_error: false

‎.github/workflows/CompatHelper.yml‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
name: CompatHelper
2+
on:
3+
schedule:
4+
- cron: 0 0 * * *
5+
workflow_dispatch:
6+
permissions:
7+
contents: read
8+
jobs:
9+
CompatHelper:
10+
runs-on: ubuntu-latest
11+
steps:
12+
- name: Pkg.add("CompatHelper")
13+
run: julia -e 'using Pkg; Pkg.add("CompatHelper")'
14+
- name: CompatHelper.main()
15+
env:
16+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
17+
COMPATHELPER_PRIV: ${{ secrets.DOCUMENTER_KEY }}
18+
run: julia -e 'using CompatHelper; CompatHelper.main()'

‎.github/workflows/Formatter.yml‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
name: Formatter
2+
on:
3+
pull_request:
4+
push:
5+
branches:
6+
- main
7+
workflow_dispatch:
8+
permissions:
9+
contents: read
10+
jobs:
11+
julia-format:
12+
name: Formatter
13+
runs-on: ubuntu-latest
14+
steps:
15+
- uses: julia-actions/setup-julia@latest
16+
- uses: actions/checkout@v6
17+
with:
18+
token: ${{ secrets.GITHUB_TOKEN }}
19+
- name: Install JuliaFormatter and format
20+
run: |
21+
julia --color=yes -e 'using Pkg; Pkg.add(PackageSpec(name="JuliaFormatter"))'
22+
julia --color=yes -e 'using JuliaFormatter; format(".", verbose=true)'
23+
- name: Commit formatted code
24+
if: github.event_name == 'workflow_dispatch'
25+
run: |
26+
git config user.name "github-actions[bot]"
27+
git config user.email "github-actions[bot]@users.noreply.github.com"
28+
git diff --quiet && exit 0
29+
git add -A
30+
git commit -m "chore: autoformat"
31+
git push
32+
- name: Format check
33+
if: github.event_name != 'workflow_dispatch'
34+
run: |
35+
julia --color=yes -e '
36+
out = Cmd(`git diff --name-only`) |> read |> String
37+
if out == ""
38+
exit(0)
39+
else
40+
@error "Some files have not been formatted !!!"
41+
write(stdout, out)
42+
exit(1)
43+
end'

‎.github/workflows/docs.yml‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
name: Documentation
2+
on:
3+
pull_request:
4+
push:
5+
branches:
6+
- main
7+
tags: ["*"]
8+
9+
repository_dispatch:
10+
types: [tagbot-release-created]
11+
12+
concurrency:
13+
# Skip intermediate builds: always.
14+
# Cancel intermediate builds: only if it is a pull request build.
15+
group: ${{ github.workflow }}-${{ github.ref }}
16+
cancel-in-progress: ${{ startsWith(github.ref, 'refs/pull/') }}
17+
jobs:
18+
docs:
19+
name: Documentation
20+
runs-on: ubuntu-latest
21+
timeout-minutes: 30
22+
permissions:
23+
contents: write
24+
statuses: write
25+
env:
26+
DOC_TEMPLATE_VERSION: "v0.7.0" # Change this to the specific tag version you want
27+
steps:
28+
- uses: actions/checkout@v7
29+
- uses: julia-actions/setup-julia@v3
30+
- uses: julia-actions/cache@v3
31+
- name: Use Documentation Template
32+
run: |
33+
./docs/get_docs_utils.sh ${{ env.DOC_TEMPLATE_VERSION }}
34+
- uses: julia-actions/julia-buildpkg@v1
35+
- uses: julia-actions/julia-docdeploy@v1
36+
env:
37+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
38+
- name: Upload documentation artifacts
39+
uses: actions/upload-artifact@v6
40+
with:
41+
name: documentation-build
42+
path: docs/build/
43+
retention-days: 1
44+
- run: |
45+
julia --project=docs -e '
46+
using Documenter: DocMeta, doctest
47+
using Intonato
48+
DocMeta.setdocmeta!(Intonato, :DocTestSetup, :(using Intonato); recursive=true)
49+
doctest(Intonato)'
50+
51+
tagbot-dispatch:
52+
name: Dispatch on TagBot Release
53+
runs-on: ubuntu-latest
54+
needs: docs
55+
if: github.event_name == 'repository_dispatch'
56+
steps:
57+
- name: Dispatch PiccoloMultiDocs workflow
58+
uses: peter-evans/repository-dispatch@v4
59+
with:
60+
token: ${{ secrets.REPO_ACCESS_TOKEN }}
61+
repository: harmoniqs/PiccoloMultiDocs.jl
62+
event-type: rebuild-docs
63+
64+
tag-push-dispatch:
65+
name: Dispatch on Tag Push
66+
runs-on: ubuntu-latest
67+
needs: docs
68+
if: github.ref_type == 'tag'
69+
steps:
70+
- name: Dispatch PiccoloMultiDocs workflow
71+
uses: peter-evans/repository-dispatch@v4
72+
with:
73+
token: ${{ secrets.REPO_ACCESS_TOKEN }}
74+
repository: harmoniqs/PiccoloMultiDocs.jl
75+
event-type: rebuild-docs

‎.github/workflows/nightly.yml‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
name: Nightly
2+
on:
3+
schedule:
4+
- cron: '00 00 * * *'
5+
workflow_dispatch:
6+
concurrency:
7+
group: ${{ github.workflow }}-${{ github.ref }}
8+
cancel-in-progress: ${{ startsWith(github.ref, 'refs/pull/') }}
9+
jobs:
10+
test:
11+
name: Julia nightly - ${{ matrix.os }} - ${{ matrix.arch }} - ${{ github.event_name }}
12+
runs-on: ${{ matrix.os }}
13+
timeout-minutes: 60
14+
permissions:
15+
actions: write
16+
contents: read
17+
strategy:
18+
fail-fast: false
19+
matrix:
20+
version:
21+
- 'pre'
22+
os:
23+
- ubuntu-latest
24+
arch:
25+
- x64
26+
steps:
27+
- uses: actions/checkout@v7
28+
- uses: julia-actions/setup-julia@v3
29+
with:
30+
version: ${{ matrix.version }}
31+
arch: ${{ matrix.arch }}
32+
- uses: julia-actions/cache@v3
33+
- uses: julia-actions/julia-buildpkg@v1
34+
- uses: julia-actions/julia-runtest@v1

‎.gitignore‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,59 @@
1+
# Files generated by invoking Julia with --code-coverage
2+
*.jl.cov
3+
*.jl.*.cov
4+
5+
# Files generated by invoking Julia with --track-allocation
6+
*.jl.mem
7+
8+
# System-specific files and directories generated by the BinaryProvider and BinDeps packages
9+
# They contain absolute paths specific to the host computer, and so should not be committed
10+
deps/deps.jl
11+
deps/build.log
12+
deps/downloads/
13+
deps/usr/
14+
deps/src/
15+
16+
# Build artifacts for creating documentation generated by the Documenter package
17+
docs/build/
18+
docs/site/
19+
docs/clones/
20+
docs/out/
21+
docs/src/generated/
22+
23+
docs/src/assets/
24+
25+
# Build artifact for using README as index (probably shouldn't have this checked into version control)
26+
docs/src/index.md
27+
28+
# File generated by Pkg, the package manager, based on a corresponding Project.toml
29+
# It records a fixed state of all packages used by the project. As such, it should not be
30+
# committed for packages, but should be committed for applications that require a static
31+
# environment.
132
Manifest.toml
33+
docs/Manifest.toml
34+
35+
# Project specific ignores below
36+
# generated example artifacts
37+
/examples/**/plots/
38+
/examples/**/trajectories/
39+
40+
# external pkgs and configs
41+
pardiso.lic
42+
/.CondaPkg/
43+
*.code-workspace
44+
45+
# generated build folder
46+
build/
47+
48+
# VS code
49+
.vscode/settings.json
50+
51+
# doc_template stuff
52+
# Temporary directory for doc_template cloning
53+
doc_template_temp/
54+
55+
# This file is updated via script
56+
docs/utils.jl
257

358
# Agent working memory (not package content)
459
.claude/

‎docs/Project.toml‎

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

‎docs/get_docs_utils.sh‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
#!/bin/bash
2+
3+
set -euo pipefail
4+
5+
# Get the directory where this script is located
6+
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
7+
PROJECT_ROOT="$SCRIPT_DIR/.."
8+
9+
# if argument is provided, use it as the DOC_TEMPLATE_VERSION
10+
if [[ $# -gt 0 ]]; then
11+
DOC_TEMPLATE_VERSION="$1"
12+
else
13+
WORKFLOW_FILE="$PROJECT_ROOT/.github/workflows/docs.yml"
14+
15+
# Check if workflow file exists
16+
if [[ ! -f "$WORKFLOW_FILE" ]]; then
17+
echo "GitHub workflow file not found at: $WORKFLOW_FILE"
18+
exit 1
19+
fi
20+
21+
DOC_TEMPLATE_VERSION=$(grep -E '^\s*DOC_TEMPLATE_VERSION:' "$WORKFLOW_FILE" | sed -E 's/.*DOC_TEMPLATE_VERSION:\s*"([^"]+)".*/\1/')
22+
fi
23+
24+
if [[ -z "$DOC_TEMPLATE_VERSION" ]]; then
25+
echo "DOC_TEMPLATE_VERSION is not set"
26+
echo "Please provide a version tag as an arg or ensure it is set in $WORKFLOW_FILE"
27+
echo "Could not extract DOC_TEMPLATE_VERSION from $WORKFLOW_FILE"
28+
echo "Expected format: DOC_TEMPLATE_VERSION: \"<version tag here>\""
29+
exit 1
30+
fi
31+
32+
# Clone the repository
33+
echo "Grabbing PiccoloDocsTemplate at version $DOC_TEMPLATE_VERSION"
34+
julia --project="$PROJECT_ROOT/docs" -e "
35+
using Pkg; Pkg.add(url=\"https://github.com/harmoniqs/PiccoloDocsTemplate.jl\", rev=\"$DOC_TEMPLATE_VERSION\")
36+
"
37+
38+
echo "Successfully updated PiccoloDocsTemplate with version $DOC_TEMPLATE_VERSION"

‎docs/make.jl‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
using Intonato
2+
using PiccoloDocsTemplate
3+
4+
pages = ["Home" => "index.md", "Library" => "lib.md"]
5+
6+
generate_docs(
7+
@__DIR__,
8+
"Intonato",
9+
[Intonato],
10+
pages;
11+
make_literate = false,
12+
make_assets = false,
13+
format_kwargs = (canonical = "https://docs.harmoniqs.co/Intonato.jl",),
14+
versions = ["dev" => "dev", "stable" => "v^", "v#.#"],
15+
)

‎docs/src/lib.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# API
2+
3+
```@meta
4+
CollapsedDocStrings = true
5+
```
6+
7+
The central entry point. `solve!(::PulseTuningProblem)` is defined as a
8+
`Piccolo.solve!` method (the function-name binding is owned by the `Piccolo` /
9+
`DirectTrajOpt` module, in scope here via Intonato's `@reexport using Piccolo`).
10+
It is documented explicitly so it is guaranteed to appear even if a future
11+
refactor changes which module owns the binding; the `@autodocs` block below is
12+
filtered to skip this method so it is not documented twice.
13+
14+
```@docs
15+
solve!(::Intonato.PulseTuningProblem)
16+
```
17+
18+
```@autodocs
19+
Modules = [Intonato]
20+
Order = [:type, :function]
21+
Filter = b -> b !== solve!
22+
```

0 commit comments

Comments
 (0)