Documentation Template Refactor (#8)

* change matrix to match others
* add same building documentation comment on README
* use PiccoloDocsTemplate instead of utils.jl
* add doctests and docstrings
* Update docs.yml

---------

Co-authored-by: Gennadi Ryan <[email protected]>

Author: jack-champagne

.github/workflows/CI.yml

@@ -18,13 +18,14 @@ jobs:
       fail-fast: false
       matrix:
         version:
-          - '1.8'
+          - '1.10'
+          - '1.11'
           - 'nightly'
         os:
           - ubuntu-latest
         arch:
           - x64
-          - x86
+          # - x86
     steps:
       - uses: actions/checkout@v2
       - uses: julia-actions/setup-julia@v1
@@ -38,24 +39,5 @@ jobs:
       - uses: codecov/codecov-action@v2
         with:
           files: lcov.info
-  docs:
-    name: Documentation
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write
-      statuses: write
-    steps:
-      - uses: actions/checkout@v2
-      - uses: julia-actions/setup-julia@v1
-        with:
-          version: '1'
-      - uses: julia-actions/julia-buildpkg@v1
-      - uses: julia-actions/julia-docdeploy@v1
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-      - run: |
-          julia --project=docs -e '
-            using Documenter: DocMeta, doctest
-            using TrajectoryIndexingUtils
-            DocMeta.setdocmeta!(TrajectoryIndexingUtils, :DocTestSetup, :(using TrajectoryIndexingUtils); recursive=true)
-            doctest(TrajectoryIndexingUtils)'
+          token: ${{ secrets.CODECOV_TOKEN }}
+          fail_ci_if_error: false

.github/workflows/docs.yml

@@ -0,0 +1,44 @@
+name: Documentation
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+    tags: ['*']
+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
+    permissions:
+      contents: write
+      statuses: write
+    env:
+      DOC_TEMPLATE_VERSION: "v0.2.1"  # Change this to the specific tag version you want
+    steps:
+      - uses: actions/checkout@v4
+      - uses: julia-actions/setup-julia@v2
+      - uses: julia-actions/cache@v2
+      - 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@v4
+        with:
+          name: documentation-build
+          path: docs/build/
+          retention-days: 1
+      - run: |
+          julia --project=docs -e '
+            using Documenter: DocMeta, doctest
+            using TrajectoryIndexingUtils
+            DocMeta.setdocmeta!(TrajectoryIndexingUtils, :DocTestSetup, :(using TrajectoryIndexingUtils; Z = collect(1.5:12.5); dim = 3); recursive=true)
+            doctest(TrajectoryIndexingUtils)'

.gitignore

@@ -16,6 +16,14 @@ 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
@@ -34,12 +42,16 @@ pardiso.lic
 /.CondaPkg/
 *.code-workspace
 
-# generated Literate
-docs/src/generated/
-
 # generated build folder
 build/
 
 # VS code
 *.code-workspace
 .vscode/settings.json
+
+# doc_template stuff
+# Temporary directory for doc_template cloning
+doc_template_temp/
+
+# This file is updated via script
+docs/utils.jl

README.md

@@ -39,11 +39,10 @@ With this, the user is still responsible for keeping track of the component indi
 
 ## Installation
 
-This package is not yet registered.  To install, use the following command:
+TrajectoryIndexingUtils.jl is registered! Install in the REPL by entering pkg mode with `]` and then running 
 
 ```julia
-using Pkg
-Pkg.add(url="https://github.com/harmoniqs/TrajectoryIndexingUtils.jl", rev="main")
+pkg> add TrajectoryIndexingUtils
 ```
 
 ## Methods 
@@ -65,10 +64,38 @@ slice(t::Int, indices::AbstractVector{Int}, dim::Int) -> zₜ[indices]
 slice(ts::UnitRange{Int}, dim::Int) -> vec(zₜ for t ∈ ts)
 ```
 
-## TODO
 
-- [ ] Add tests
-- [ ] Add examples 
-- [ ] Add documentation 
-- [ ] Add methods that take in trajectory vector as the first argument
-- [ ] Add `block` function for accessing blocks of matrices with trajectory structure, e.g. jacobians & hessians
+### Building Documentation
+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. 
+```
+# first time only
+./docs/get_docs_utils.sh   # or ./get_docs_utils.sh if cwd is in ./docs/
+```
+
+To build the docs pages:
+```
+julia --project=docs docs/make.jl
+```
+
+or editing the docs live:
+```
+julia --project=docs
+> using LiveServer, Piccolo, Revise
+> servedocs(skip_files=["docs/src/index.md"])
+```
+
+> **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.
+> 
+> To prevent this, ensure all generated files are included in the skip dirs or skip files args for `servedocs`.
+
+For example, if we forget index.md like so:
+```
+julia --project=docs
+> using LiveServer, Piccolo, Revise
+> servedocs()
+```
+it will not build and serve.
+
+-----
+
+*"It seems that perfection is attained not when there is nothing more to add, but when there is nothing more to take away." - Antoine de Saint-Exupéry*

docs/Project.toml

@@ -1,3 +1,7 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
+LiveServer = "16fef848-5104-11e9-1b77-fb7a48bbb589"
+PiccoloDocsTemplate = "a90a139f-c522-4b23-980b-4210ddb8d065"
+Revise = "295af30f-e4ad-537b-8983-00126c2a3abe"
 TrajectoryIndexingUtils = "6dad8b7f-dd9a-4c28-9b70-85b9a079bfc8"

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

@@ -1,25 +1,21 @@
 using TrajectoryIndexingUtils
-using Documenter
+using PiccoloDocsTemplate
 
-DocMeta.setdocmeta!(TrajectoryIndexingUtils, :DocTestSetup, :(using TrajectoryIndexingUtils); recursive=true)
+pages=[
+    "Home" => "index.md",
+    "Library" => "lib.md",
+]
 
-makedocs(;
-    modules=[TrajectoryIndexingUtils],
-    authors="Aaron Trowbridge <[email protected]> and contributors",
-    repo="https://github.com/harmoniqs/TrajectoryIndexingUtils.jl/blob/{commit}{path}#{line}",
-    sitename="TrajectoryIndexingUtils.jl",
-    format=Documenter.HTML(;
-        prettyurls=get(ENV, "CI", "false") == "true",
-        canonical="https://docs.harmoniqs.co/TrajectoryIndexingUtils.jl",
-        edit_link="main",
-        assets=String[],
+generate_docs(
+    @__DIR__,
+    "TrajectoryIndexingUtils",
+    TrajectoryIndexingUtils,
+    pages;
+    make_assets = false,
+    make_index = true,
+    make_literate = false,
+    format_kwargs = (canonical = "https://docs.harmoniqs.co/TrajectoryIndexingUtils.jl",),
+    doctest_setup_meta_args = Dict(
+        TrajectoryIndexingUtils => :(using TrajectoryIndexingUtils; Z = collect(1.5:12.5); dim = 3),
     ),
-    pages=[
-        "Home" => "index.md",
-    ],
-)
-
-deploydocs(;
-    repo="github.com/harmoniqs/TrajectoryIndexingUtils.jl",
-    devbranch="main",
-)
+)

docs/src/index.md

@@ -0,0 +1,49 @@
+## TrajectoryIndexingUtils methods
+
+This module contains helper functions for indexing and taking slices of the full problem variable vector
+definitions:
+
+* problem vector: 
+    Z = [z₁, z₂, ..., zₜ]
+
+* knot point:
+    zₜ = [xₜ, uₜ]
+
+* augmented state vector:
+    xₜ = [ψ̃ₜ, ψ̃²ₜ, ..., ψ̃ⁿₜ, ∫aₜ, aₜ, daₜ, ..., dᶜ⁻¹aₜ]
+
+where c = control_order
+
+also, below, we use `dim(zₜ) = dim`
+examples:
+```julia
+Z[index(t, pos, dim)]               = zₜ[pos]
+Z[index(t, dim)]                    = zₜ[dim]
+Z[slice(t, pos1, pos2, dim)]        = zₜ[pos1:pos2]
+Z[slice(t, pos, dim)]               = zₜ[1:pos]
+Z[slice(t, dim)]                    = zₜ[1:dim] := zₜ
+Z[slice(t, dim; stretch=stretch)]   = zₜ[1:(dim + stretch)]
+Z[slice(t, indices, dim)]           = zₜ[indices]
+Z[slice(t1:t2, dim)]                = [zₜ₁;...;zₜ₂]
+```
+
+The functions are also used to access the zₜ vectors, e.g.
+```julia
+zₜ[slice(i, isodim)]                             = ψ̃ⁱₜ
+zₜ[n_wfn_states .+ slice(1, ncontrols)]          = ∫aₜ
+zₜ[n_wfn_states .+ slice(2, ncontrols)]          = aₜ
+zₜ[n_wfn_states .+ slice(augdim + 1, ncontrols)] = uₜ = ddaₜ
+```
+
+Examples below are run with:
+```julia
+using TrajectoryIndexingUtils
+Z = collect(1.5:12.5)  # Example vector as Float64
+dim = 3  # Example dimension
+```
+
+## API 
+
+```@autodocs
+Modules = [TrajectoryIndexingUtils]
+```