Document all public symbols [skip tests]

Author: gdalle

.github/workflows/Test.yml

@@ -125,7 +125,7 @@ jobs:
       - uses: actions/checkout@v5
       - uses: julia-actions/setup-julia@v2
         with:
-          version: '1.10'
+          version: '1.11'
       - name: Develop packages
         run: |
           julia -e "

docs/Project.toml

@@ -1,5 +1,13 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+GPUArrays = "0c68f7d7-f131-5f86-a1c3-88cf8149b2d7"
+GPUArraysCore = "46192b85-c4d5-4398-a991-12ede77f4527"
+JLArrays = "27aeb0d3-9eb9-45fb-866b-73c2ecf80fcb"
 
 [compact]
 Documenter = "1.8"
+
+[sources]
+GPUArrays = {path = ".."}
+GPUArraysCore = {path = "../lib/GPUArraysCore"}
+JLArrays = {path = "../lib/JLArrays"}

docs/make.jl

@@ -1,8 +1,8 @@
-using Documenter, GPUArrays
+using Documenter, GPUArrays, GPUArraysCore, JLArrays
 
 function main()
     makedocs(
-        modules = [GPUArrays],
+        modules = [GPUArrays, GPUArraysCore, JLArrays],
         format = Documenter.HTML(
             # Use clean URLs on CI
             prettyurls = get(ENV, "CI", nothing) == "true",
@@ -11,19 +11,15 @@ function main()
         ),
         sitename = "GPUArrays.jl",
         pages = [
-            "Home"          => "index.md",
-            "Interface"     => "interface.md",
-            "Functionality" => [
-                "functionality/host.md",
-                "functionality/device.md",
-            ],
-            "Test suite"    => "testsuite.md",
+            "Home" => "index.md",
+            "interface.md",
+            "api.md",
         ],
         doctest = true,
         warnonly = [:missing_docs],
     )
 
-    deploydocs(
+    return deploydocs(
         repo = "github.com/JuliaGPU/GPUArrays.jl.git"
     )
 end

docs/src/api.md

@@ -0,0 +1,49 @@
+# API Reference
+
+## GPUArrays
+
+### Public
+
+```@autodocs
+Modules = [GPUArrays]
+Private = false
+```
+
+### Internals
+
+```@autodocs
+Modules = [GPUArrays]
+Public = false
+```
+
+## GPUArraysCore
+
+### Public
+
+```@autodocs
+Modules = [GPUArraysCore]
+Private = false
+```
+
+### Internals
+
+```@autodocs
+Modules = [GPUArraysCore]
+Public = false
+```
+
+## JLArrays
+
+### Public
+
+```@autodocs
+Modules = [JLArrays]
+Private = false
+```
+
+### Internals
+
+```@autodocs
+Modules = [JLArrays]
+Public = false
+```

docs/src/functionality/device.md

@@ -1,6 +1,6 @@
 # Interface
 
-To extend the above functionality to a new array type, you should use the types and
+To extend the GPUArrays functionality to a new array type, you should use the types and
 implement the interfaces listed on this page. GPUArrays is designed around having two
 different array types to represent a GPU array: one that exists only on the host, and
 one that actually can be instantiated on the device (i.e. in kernels).
@@ -31,9 +31,45 @@ KernelAbstractions.get_backend(a::CA) where CA <: CustomArray = CustomBackend()
 
 There are numerous examples of potential interfaces for GPUArrays, such as with [JLArrays](https://github.com/JuliaGPU/GPUArrays.jl/blob/master/lib/JLArrays/src/JLArrays.jl), [CuArrays](https://github.com/JuliaGPU/CUDA.jl/blob/master/src/gpuarrays.jl), and [ROCArrays](https://github.com/JuliaGPU/AMDGPU.jl/blob/master/src/gpuarrays.jl).
 
-## Caching Allocator
+## Device abstractions
 
-```@docs
-GPUArrays.@cached
-GPUArrays.@uncached
+!!! warning
+    Work in progress.
+
+## Test suite
+
+GPUArrays provides an extensive test suite that covers all of the functionality that should
+be available after implementing the required interfaces. This test suite is part of this
+package, but for dependency reasons it is not available when importing the package. Instead,
+you should include the code from your `runtests.jl` as follows:
+
+```julia
+import GPUArrays
+gpuarrays = pathof(GPUArrays)
+gpuarrays_root = dirname(dirname(gpuarrays))
+include(joinpath(gpuarrays_root, "test", "testsuite.jl"))
+```
+
+With this set-up, you can run the test suite like this:
+
+```julia
+TestSuite.test(MyGPUArrayType)
+```
+
+If you don't want to run the whole suite, you can also run parts of it:
+
+```julia
+T = JLArray
+GPUArrays.allowscalar(false) # fail tests when slow indexing path into Array type is used.
+
+TestSuite.test_gpuinterface(T) # interface functions like gpu_call, threadidx, etc
+TestSuite.test_base(T) # basic functionality like launching a kernel on the GPU and Base operations
+TestSuite.test_blas(T) # tests the blas interface
+TestSuite.test_broadcasting(T) # tests the broadcasting implementation
+TestSuite.test_construction(T) # tests all kinds of different ways of constructing the array
+TestSuite.test_linalg(T) # linalg function tests
+TestSuite.test_mapreduce(T) # mapreduce sum, etc
+TestSuite.test_indexing(T) # indexing tests
+TestSuite.test_random(T) # randomly constructed arrays
+TestSuite.test_io(T)
 ```

docs/src/functionality/host.md

@@ -13,26 +13,69 @@ export AbstractGPUArray, AbstractGPUVector, AbstractGPUMatrix, AbstractGPUVecOrM
     AbstractGPUArray{T, N} <: DenseArray{T, N}
 
 Supertype for `N`-dimensional GPU arrays (or array-like types) with elements of type `T`.
-Instances of this type are expected to live on the host, see [`AbstractDeviceArray`](@ref)
+Instances of this type are expected to live on the host, see `AbstractDeviceArray`
 for device-side objects.
 """
 abstract type AbstractGPUArray{T, N} <: DenseArray{T, N} end
 
+"""
+    AbstractGPUVector{T}
+
+Shortcut for `AbstractGPUArray{T, 1}`.
+"""
 const AbstractGPUVector{T} = AbstractGPUArray{T, 1}
+
+"""
+    AbstractGPUMatrixT}
+
+Shortcut for `AbstractGPUArray{T, 2}`.
+"""
 const AbstractGPUMatrix{T} = AbstractGPUArray{T, 2}
+
+"""
+    AbstractGPUVecOrMat{T}
+
+Shortcut for `Union{AbstractGPUArray{T, 1}, AbstractGPUArray{T, 2}}`.
+"""
 const AbstractGPUVecOrMat{T} = Union{AbstractGPUArray{T, 1}, AbstractGPUArray{T, 2}}
 
 # convenience aliases for working with wrapped arrays
+
+"""
+    WrappedGPUArray{T, N}
+
+Convenience alias for working with wrapped arrays from [Adapt.jl](https://github.com/JuliaGPU/Adapt.jl).
+"""
 const WrappedGPUArray{T,N} = WrappedArray{T,N,AbstractGPUArray,AbstractGPUArray{T,N}}
+
+"""
+    AnyGPUArray{T, N}
+
+Shortcut for `Union{AbstractGPUArray{T,N}, WrappedGPUArray{T,N}}`.
+"""
 const AnyGPUArray{T,N} = Union{AbstractGPUArray{T,N}, WrappedGPUArray{T,N}}
+
+"""
+    AnyGPUVector{T}
+
+Shortcut for `AnyGPUArray{T, 1}`.
+"""
 const AnyGPUVector{T} = AnyGPUArray{T, 1}
+
+"""
+    AnyGPUMatrix{T}
+
+Shortcut for `AnyGPUArray{T, 2}`.
+"""
 const AnyGPUMatrix{T} = AnyGPUArray{T, 2}
 
 
 ## broadcasting
 
 """
-Abstract supertype for GPU array styles. The `N` parameter is the dimensionality.
+    AbstractGPUArrayStyle{N} <: Base.Broadcast.AbstractArrayStyle{N}
+
+Abstract supertype for GPU array broadcasting styles. The `N` parameter is the dimensionality.
 
 Downstream implementations should provide a concrete array style type that inherits from
 this supertype.