Skip to content

Commit 369e4c6

Browse files
jack-champagnegennadiryan
jack-champagne
and
gennadiryan
authored
Documentation Template Refactor (#213)
* update readme for docs building instructions * use new docs CI separate from rest * use PiccoloDocsTemplate * minor docs fixes --------- Co-authored-by: Gennadi Ryan <gennadiryan@gmail.com> Co-authored-by: Gennadi Ryan <41800392+gennadiryan@users.noreply.github.com>
1 parent bb7ecec commit 369e4c6

12 files changed

Lines changed: 179 additions & 107 deletions

File tree

‎.github/workflows/CI.yml‎

Lines changed: 1 addition & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -39,25 +39,4 @@ jobs:
3939
with:
4040
files: lcov.info
4141
token: ${{ secrets.CODECOV_TOKEN }}
42-
fail_ci_if_error: false
43-
docs:
44-
name: Documentation
45-
runs-on: ubuntu-latest
46-
permissions:
47-
contents: write
48-
statuses: write
49-
steps:
50-
- uses: actions/checkout@v2
51-
- uses: julia-actions/setup-julia@v1
52-
with:
53-
version: '1'
54-
- uses: julia-actions/julia-buildpkg@v1
55-
- uses: julia-actions/julia-docdeploy@v1
56-
env:
57-
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
58-
- run: |
59-
julia --project=docs -e '
60-
using Documenter: DocMeta, doctest
61-
using QuantumCollocation
62-
DocMeta.setdocmeta!(QuantumCollocation, :DocTestSetup, :(using QuantumCollocation); recursive=true)
63-
doctest(QuantumCollocation)'
42+
fail_ci_if_error: false

‎.github/workflows/docs.yml‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
name: Documentation
2+
on:
3+
pull_request:
4+
push:
5+
branches:
6+
- main
7+
tags: ['*']
8+
concurrency:
9+
# Skip intermediate builds: always.
10+
# Cancel intermediate builds: only if it is a pull request build.
11+
group: ${{ github.workflow }}-${{ github.ref }}
12+
cancel-in-progress: ${{ startsWith(github.ref, 'refs/pull/') }}
13+
jobs:
14+
docs:
15+
name: Documentation
16+
runs-on: ubuntu-latest
17+
permissions:
18+
contents: write
19+
statuses: write
20+
env:
21+
DOC_TEMPLATE_VERSION: "v0.2.1" # Change this to the specific tag version you want
22+
steps:
23+
- uses: actions/checkout@v4
24+
- uses: julia-actions/setup-julia@v2
25+
- uses: julia-actions/cache@v2
26+
- name: Use Documentation Template
27+
run: |
28+
./docs/get_docs_utils.sh ${{ env.DOC_TEMPLATE_VERSION }}
29+
- uses: julia-actions/julia-buildpkg@v1
30+
- uses: julia-actions/julia-docdeploy@v1
31+
env:
32+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
33+
- name: Upload documentation artifacts
34+
uses: actions/upload-artifact@v4
35+
with:
36+
name: documentation-build
37+
path: docs/build/
38+
retention-days: 1
39+
- run: |
40+
julia --project=docs -e '
41+
using Documenter: DocMeta, doctest
42+
using QuantumCollocation
43+
DocMeta.setdocmeta!(QuantumCollocation, :DocTestSetup, :(using QuantumCollocation); recursive=true)
44+
doctest(QuantumCollocation)'
45+

‎.github/workflows/documentation.yml‎

Lines changed: 0 additions & 26 deletions
This file was deleted.

‎.gitignore‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,3 +45,10 @@ build/
4545
# VS code
4646
*.code-workspace
4747
.vscode/settings.json
48+
49+
# doc_template stuff
50+
# Temporary directory for doc_template cloning
51+
doc_template_temp/
52+
53+
# This file is updated via script
54+
docs/utils.jl

‎README.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -91,3 +91,35 @@ U_goal = GATES.H
9191
prob = UnitarySmoothPulseProblem(system, U_goal, T, Δt)
9292
solve!(prob, max_iter=100)
9393
```
94+
95+
96+
### Building Documentation
97+
This package uses a Documenter config that is shared with many of our other repositories. To build the docs, you will need to run the docs setup script to clone and pull down the utility.
98+
```
99+
# first time only
100+
./docs/get_docs_utils.sh # or ./get_docs_utils.sh if cwd is in ./docs/
101+
```
102+
103+
To build the docs pages:
104+
```
105+
julia --project=docs docs/make.jl
106+
```
107+
108+
or editing the docs live:
109+
```
110+
julia --project=docs
111+
> using LiveServer, QuantumCollocation, Revise
112+
> servedocs(literate_dir="docs/literate", skip_dirs=["docs/src/generated"])
113+
```
114+
115+
> **Note:** `servedocs` needs to watch a subset of the files in the `docs/` folder. If it watches files that are generated on a docs build/re-build, `servedocs` will continuously try to re-serve the pages.
116+
>
117+
> To prevent this, ensure all generated files are included in the skip dirs or skip files args for `servedocs`.
118+
119+
For example, if we forget docs/src/generated like so:
120+
```
121+
julia --project=docs
122+
> using LiveServer, Piccolo, Revise
123+
> servedocs(literate_dir="docs/literate")
124+
```
125+
it will not build and serve.

‎docs/Project.toml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
44
Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
55
LiveServer = "16fef848-5104-11e9-1b77-fb7a48bbb589"
66
NamedTrajectories = "538bc3a1-5ab9-4fc3-b776-35ca1e893e08"
7+
PiccoloDocsTemplate = "a90a139f-c522-4b23-980b-4210ddb8d065"
78
PiccoloPlots = "f42a522c-b487-4f73-ad5a-ad0c3e4a12c8"
89
PiccoloQuantumObjects = "5a402ddf-f93c-42eb-975e-5582dcda653d"
910
QuantumCollocation = "0dc23a59-5ffb-49af-b6bd-932a8ae77adf"

‎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 & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -1,66 +1,25 @@
11
using QuantumCollocation
2-
using Documenter
3-
using Literate
4-
5-
push!(LOAD_PATH, joinpath(@__DIR__, "..", "src"))
6-
7-
@info "Building Documenter site for QuantumCollocation.jl"
2+
using PiccoloDocsTemplate
83

94
pages = [
105
"Home" => "index.md",
6+
"Manual" => [
7+
"Ket Problem Templates" => "generated/man/ket_problem_templates.md",
8+
"Unitary Problem Templates" => "generated/man/unitary_problem_templates.md",
9+
],
1110
"Examples" => [
1211
"Two Qubit Gates" => "generated/examples/two_qubit_gates.md",
1312
"Multilevel Transmon" => "generated/examples/multilevel_transmon.md",
1413
],
15-
"Library" => [
16-
"Ket Problem Templates" => "generated/man/ket_problem_templates.md",
17-
"Unitary Problem Templates" => "generated/man/unitary_problem_templates.md",
18-
],
14+
"Library" => "lib.md",
1915
]
2016

21-
format = Documenter.HTML(;
22-
prettyurls=get(ENV, "CI", "false") == "true",
23-
canonical="https://docs.harmoniqs.co/QuantumCollocation.jl",
24-
edit_link="main",
25-
assets=String[],
26-
mathengine = MathJax3(Dict(
27-
:loader => Dict("load" => ["[tex]/physics"]),
28-
:tex => Dict(
29-
"inlineMath" => [["\$","\$"], ["\\(","\\)"]],
30-
"tags" => "ams",
31-
"packages" => [
32-
"base",
33-
"ams",
34-
"autoload",
35-
"physics"
36-
],
37-
),
38-
)),
39-
# size_threshold=4_000_000,
40-
)
41-
42-
src = joinpath(@__DIR__, "src")
43-
lit = joinpath(@__DIR__, "literate")
44-
45-
lit_output = joinpath(src, "generated")
46-
47-
for (root, _, files) ∈ walkdir(lit), file ∈ files
48-
splitext(file)[2] == ".jl" || continue
49-
ipath = joinpath(root, file)
50-
opath = splitdir(replace(ipath, lit=>lit_output))[1]
51-
Literate.markdown(ipath, opath)
52-
end
53-
54-
makedocs(;
55-
modules=[QuantumCollocation],
56-
authors="Aaron Trowbridge <aaron.j.trowbridge@gmail.com> and contributors",
57-
sitename="QuantumCollocation.jl",
58-
format=format,
59-
pages=pages,
60-
warnonly=true,
61-
)
62-
63-
deploydocs(;
64-
repo="github.com/harmoniqs/QuantumCollocation.jl.git",
65-
devbranch="main",
66-
)
17+
generate_docs(
18+
@__DIR__,
19+
"QuantumCollocation",
20+
[QuantumCollocation],
21+
pages;
22+
make_index = false,
23+
make_assets = false,
24+
format_kwargs = (canonical = "https://docs.harmoniqs.co/QuantumCollocation.jl",),
25+
)

‎docs/src/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -59,4 +59,4 @@ In each case, the dynamics between *knot points* $(U_t, a_t)$ and $(U_{t+1}, a_{
5959

6060
-----
6161

62-
Problem templates give the user the ability to add other constraints and objective functions to this problem and solve it efficiently using [Ipopt.jl](https://github.com/jump-dev/Ipopt.jl) and [MathOptInterface.jl](https://github.com/jump-dev/MathOptInterface.jl) under the hood.
62+
Problem templates give the user the ability to add other constraints and objective functions to this problem and solve it efficiently using [Ipopt.jl](https://github.com/jump-dev/Ipopt.jl) and [MathOptInterface.jl](https://github.com/jump-dev/MathOptInterface.jl) under the hood (support for additional backends coming soon!).

‎docs/src/lib.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,26 @@
55
Modules = [QuantumCollocation.ProblemTemplates]
66
```
77

8+
## Quantum System Templates
9+
```@autodocs
10+
Modules = [QuantumCollocation.QuantumSystemTemplates]
11+
```
12+
13+
## Quantum Objectives
14+
```@autodocs
15+
Modules = [QuantumCollocation.QuantumObjectives]
16+
```
17+
18+
## Quantum Constraints
19+
```@autodocs
20+
Modules = [QuantumCollocation.QuantumObjectives]
21+
```
22+
23+
## Quantum Integrators
24+
```@autodocs
25+
Modules = [QuantumCollocation.QuantumObjectives]
26+
```
27+
828
## Options
929
```@autodocs
1030
Modules = [QuantumCollocation.Options]

0 commit comments

Comments
 (0)