Improve public API docs and expand the manual.

.github/workflows/ci.yml

@@ -1,19 +1,23 @@
 name: CI-KA
+
 on:
   push:
     branches:
       - main
       - release-*
     tags: '*'
   pull_request:
+
 defaults:
   run:
     shell: bash
+
 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:
   CI:
     name: CI
@@ -159,6 +163,7 @@ jobs:
       - uses: codecov/codecov-action@v6
         with:
           files: lcov.info
+
   OpenCL:
     name: OpenCL (POCL)
     runs-on: ubuntu-latest
@@ -193,6 +198,7 @@ jobs:
       - uses: codecov/codecov-action@v6
         with:
           files: lcov.info
+
   docs:
     name: Documentation
     runs-on: ubuntu-latest
@@ -201,12 +207,24 @@ jobs:
       - uses: julia-actions/setup-julia@v3
         with:
           version: '1'
-      - run: |
-          julia --project=docs -e 'import Pkg; Pkg.develop(path=".")'
-          julia --project=docs docs/make.jl
+      - uses: julia-actions/cache@v3
+      - name: "Instantiate docs environment"
+        shell: julia --project=docs --color=yes {0}
+        run: |
+          using Pkg
+          Pkg.instantiate()
+      - name: "Build docs"
+        run: |
+          julia --project=docs --color=yes docs/make.jl
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}
+      - name: Upload build artefact
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: docs/build
+          name: docs-build
+
   doctests:
     name: Doctests
     runs-on: ubuntu-latest
@@ -215,9 +233,13 @@ jobs:
       - uses: julia-actions/setup-julia@v3
         with:
           version: '1'
-      - run: |
-          julia --project=docs -e 'import Pkg; Pkg.develop(path=".")'
-          julia --project=docs -e '
-            using Documenter: doctest
-            using KernelAbstractions
-            doctest(KernelAbstractions; manual = true)'
+      - uses: julia-actions/cache@v3
+      - name: "Run doctests"
+        shell: julia --project=docs --color=yes {0}
+        run: |
+          using Pkg
+          Pkg.instantiate()
+
+          using Documenter: doctest
+          using KernelAbstractions
+          doctest(KernelAbstractions; manual = true)

docs/Project.toml

@@ -1,5 +1,9 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+KernelAbstractions = "63c18a36-062a-441e-b654-da1e3ab1ce7c"
 
 [compat]
 Documenter = "1"
+
+[sources]
+KernelAbstractions = {path = ".."}

docs/make.jl

@@ -1,5 +1,3 @@
-push!(Base.LOAD_PATH, dirname(@__DIR__))
-
 using KernelAbstractions
 using Documenter
 

docs/src/api.md

@@ -13,21 +13,69 @@
 @uniform
 @groupsize
 @ndrange
-synchronize
-allocate
 ```
 
 ## Host language
 
+### Backends and arrays
+
 ```@docs
+Backend
+GPU
+CPU
+POCLBackend
+get_backend
+KernelAbstractions.allocate
 KernelAbstractions.zeros
+KernelAbstractions.ones
+KernelAbstractions.copyto!
+KernelAbstractions.pagelock!
+KernelAbstractions.unsafe_free!
+KernelAbstractions.functional
+KernelAbstractions.versioninfo
 KernelAbstractions.supports_unified
+KernelAbstractions.supports_atomics
+KernelAbstractions.supports_float64
 ```
 
-## Internal
+### Devices and execution
+
+```@docs
+synchronize
+KernelAbstractions.device
+KernelAbstractions.ndevices
+KernelAbstractions.device!
+KernelAbstractions.priority!
+```
+
+### Kernel handles
 
 ```@docs
 KernelAbstractions.Kernel
+KernelAbstractions.workgroupsize
+KernelAbstractions.ndrange
+KernelAbstractions.backend
+```
+
+## Reflection
+
+These macros help inspect the generated kernel code. GPU LLVM reflection is only supported
+on the CPU backend via [`@ka_code_llvm`](@ref).
+
+```@docs
+@ka_code_typed
+@ka_code_llvm
+```
+
+## Internal
+
+The functionalities in this section are considered internal and not part of the public API contract.
+They are only documented here for developers and contributors of `KernelAbstractions.jl`, but should not be used by end users (and if they do, they should expect breakage without notice).
+
+```@docs
 KernelAbstractions.partition
 KernelAbstractions.@context
+KernelAbstractions.argconvert
+KernelAbstractions.NDIteration.DynamicSize
+KernelAbstractions.NDIteration.StaticSize
 ```

docs/src/examples/memcopy_static.md

@@ -1,4 +1,4 @@
-# Memcopy with static NDRange
+# [Memcopy with static NDRange](@id memcopy_static)
 
 The first example simple copies memory from `B` to `A`. In contrast to the previous examples
 it uses a fully static kernel configuration. Specializing the kernel on the iteration range itself.

docs/src/implementations.md

@@ -1,4 +1,4 @@
-# Notes for backend implementations
+# [Notes for backend implementations](@id implementations_notes)
 
 ## Semantics of `KernelAbstractions.synchronize`