setup Documenter (#11)

Author: vchuravy

.github/workflows/Cleanup.yml

@@ -0,0 +1,33 @@
+name: Doc Preview Cleanup
+
+on:
+  pull_request:
+    types: [closed]
+
+# Ensure that only one "Doc Preview Cleanup" workflow is force pushing at a time
+concurrency:
+  group: doc-preview-cleanup
+  cancel-in-progress: false
+
+jobs:
+  doc-preview-cleanup:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout gh-pages branch
+        uses: actions/checkout@v4
+        with:
+          ref: gh-pages
+      - name: Delete preview and history + push changes
+        run: |
+          if [ -d "${preview_dir}" ]; then
+              git config user.name "Documenter.jl"
+              git config user.email "[email protected]"
+              git rm -rf "${preview_dir}"
+              git commit -m "delete preview"
+              git branch gh-pages-new $(echo "delete history" | git commit-tree HEAD^{tree})
+              git push --force origin gh-pages-new:gh-pages
+          fi
+        env:
+          preview_dir: previews/PR${{ github.event.number }}

.github/workflows/Documentation.yml

@@ -0,0 +1,42 @@
+name: Documentation
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+    tags: "*"
+
+# needed to allow julia-actions/cache to delete old caches that it has created
+permissions:
+  actions: write
+  contents: read
+
+jobs:
+  docs:
+    name: Documentation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: julia-actions/setup-julia@v2
+        with:
+          version: "1"
+      - uses: julia-actions/cache@v2
+      - name: instantiate docs
+        run: |
+          julia --project=docs -e '
+            using Pkg
+            Pkg.instantiate()
+          '
+      - name: run doctests
+        run: |
+          julia --project=docs -e '
+            using Documenter: DocMeta, doctest
+            using GPUToolbox
+            DocMeta.setdocmeta!(GPUToolbox, :DocTestSetup, :(using GPUToolbox); recursive=true)
+            doctest(GPUToolbox)
+          '
+      - name: generate docs
+        run: julia --project=docs docs/make.jl
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}

docs/.gitignore

@@ -0,0 +1,2 @@
+Manifest.toml
+build

docs/Project.toml

@@ -0,0 +1,10 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+GPUToolbox = "096a3bc2-3ced-46d0-87f4-dd12716f4bfc"
+
+[sources]
+GPUToolbox = {path = ".."}
+
+[compat]
+Documenter = "1.8"
+julia = "1.11"

docs/make.jl

@@ -0,0 +1,28 @@
+using GPUToolbox
+using Documenter
+import Documenter.Remotes: GitHub
+
+DocMeta.setdocmeta!(GPUToolbox, :DocTestSetup, :(using GPUToolbox); recursive = true)
+
+makedocs(;
+    modules = [GPUToolbox],
+    authors = "",
+    repo = GitHub("JuliaGPU", "GPUToolbox.jl"),
+    sitename = "GPUToolbox.jl",
+    format = Documenter.HTML(;
+        prettyurls = get(ENV, "CI", "false") == "true",
+        canonical = "https://juliagpu.com/GPUToolbox.jl",
+        mathengine = MathJax3(),
+    ),
+    pages = [
+        "Home" => "index.md",
+    ],
+    doctest = true,
+    linkcheck = true,
+)
+
+deploydocs(;
+    repo = "github.com/JuliaGPU/GPUToolbox.jl.git",
+    devbranch = "main",
+    push_preview = true,
+)

docs/src/index.md

@@ -0,0 +1,7 @@
+# GPUToolbox.jl
+
+## API
+
+```@autodocs
+Modules = [GPUToolbox]
+```

src/ccalls.jl

@@ -98,9 +98,9 @@ render_arg(io, arg::Base.RefValue{T}) where {T} = print(io, "Ref{", T, "}")
 const HAS_CCALL_GCSAFE = VERSION >= v"1.13.0-DEV.70" || v"1.12-DEV.2029" <= VERSION < v"1.13-"
 
 """
-@gcsafe_ccall ...
+    @gcsafe_ccall ...
 
-Call a foreign function just like `@ccall`, but marking it safe for the GC to run. This is
+Call a foreign function just like [`@ccall`](https://docs.julialang.org/en/v1/base/c/#Base.@ccall), but marking it safe for the GC to run. This is
 useful for functions that may block, so that the GC isn't blocked from running, but may also
 be required to prevent deadlocks (see JuliaGPU/CUDA.jl#2261).