Init documentation with direct reco example

.github/workflows/CI.yml

@@ -48,3 +48,25 @@ jobs:
             ${{ runner.os }}-
       - uses: julia-actions/julia-buildpkg@v1
       - uses: julia-actions/julia-runtest@v1
+
+  docs:
+    name: Documentation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: julia-actions/setup-julia@v1
+        with:
+          version: '1'
+      - run: |
+          julia --project=docs -e '
+            using Pkg
+            Pkg.develop(PackageSpec(path=pwd()))
+            Pkg.instantiate()'
+      - run: |
+          julia --project=docs -e '
+            using Documenter: DocMeta, doctest
+            using AbstractImageReconstruction'
+      - run: julia --project=docs docs/make.jl
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}

.gitignore

@@ -1 +1,10 @@
+*.jl.cov
+*.jl.*.cov
+*.jl.mem
+docs/build/
+docs/site/
+docs/src/generated/
+
+Manifest.toml
+
 /Manifest.toml

README.md

@@ -2,6 +2,9 @@
 
 [![Build Status](https://github.com/JuliaImageRecon/AbstractImageReconstruction.jl/actions/workflows/CI.yml/badge.svg?branch=main)](https://github.com/JuliaImageRecon/AbstractImageReconstruction.jl/actions/workflows/CI.yml?query=branch%3Amain)
 
+[![](https://img.shields.io/badge/docs-latest-blue.svg)](https://JuliaImageRecon.github.io/AbstractImageReconstruction.jl/latest)
+
+
 This package contains an interface and type hierarchy for image reconstruction algorithms and their parameters, together with associated utility tools.
 
 ## Installation

docs/Project.toml

@@ -0,0 +1,14 @@
+[deps]
+AbstractImageReconstruction = "a4b4fdbf-6459-4ec9-990d-77e1fa24a91b"
+BenchmarkTools = "6e4b80f9-dd63-53aa-95a3-0cdb28fa8baf"
+CairoMakie = "13f3f980-e62b-5c42-98c6-ff1f3baf88f0"
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+ImageGeoms = "9ee76f2b-840d-4475-b6d6-e485c9297852"
+ImagePhantoms = "71a99df6-f52c-4da1-bd2a-69d6f37f3252"
+LinearOperatorCollection = "a4a2c56f-fead-462a-a3ab-85921a5f2575"
+Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
+RadonKA = "86de8297-835b-47df-b249-c04e8db91db5"
+RegularizedLeastSquares = "1e9c538a-f78c-5de5-8ffb-0b6dbe892d23"
+
+[compat]
+Documenter = "1"

docs/make.jl

@@ -0,0 +1,51 @@
+using Documenter, Literate, AbstractImageReconstruction
+
+# Generate examples
+OUTPUT_BASE = joinpath(@__DIR__(), "src/generated")
+INPUT_BASE = joinpath(@__DIR__(), "src/literate")
+for (_, dirs, _) in walkdir(INPUT_BASE)
+    for dir in dirs
+        OUTPUT = joinpath(OUTPUT_BASE, dir)
+        INPUT = joinpath(INPUT_BASE, dir)
+        for file in filter(f -> endswith(f, ".jl"), readdir(INPUT))
+            Literate.markdown(joinpath(INPUT, file), OUTPUT)
+        end
+    end
+end
+
+makedocs(
+    format = Documenter.HTML(;
+        prettyurls=get(ENV, "CI", "false") == "true",
+        canonical="https://github.com/JuliaImageRecon/AbstractImageReconstruction.jl",
+        assets=String[],
+        collapselevel=1,
+    ),
+    repo="https://github.com/JuliaImageRecon/AbstractImageReconstruction.jl/blob/{commit}{path}#{line}",
+    modules = [AbstractImageReconstruction],
+    sitename = "AbstractImageReconstruction.jl",
+    authors = "Niklas Hackelberg, Tobias Knopp",
+    pages = [
+        "Home" => "index.md",
+        "Example: Radon Reconstruction Package" => Any[
+            "Introduction" => "example_intro.md",
+            "Radon Data" => "generated/example/0_radon_data.md",
+            "Interface" => "generated/example/1_interface.md",
+            "Direct Reconstruction" => "generated/example/2_direct.md",
+            "Direct Reconstruction Result" => "generated/example/3_direct_result.md",
+        ],
+        "How to" => Any[
+            #"Construct RecoPlan" => "generated/howto/reco_plan.md",
+            #"Caching" => "generated/howto/caching.md",
+            #"Listeners" => "generated/howto/listeners.md",
+        ],
+        #"API Reference" => Any["Solvers" => "API/solvers.md",
+        #"Regularization Terms" => "API/regularization.md"],
+
+    ],
+    pagesonly = true,
+    checkdocs = :none,
+    doctest   = false,
+    doctestfilters = [r"(\d*)\.(\d{4})\d+"]
+    )
+
+deploydocs(repo   = "github.com/JuliaImageRecon/AbstractImageReconstruction.jl.git", push_preview = true)

docs/src/API/algorithm.md

@@ -0,0 +1,52 @@
+# API for Regularizers
+This page contains documentation of the public API of the RegularizedLeastSquares. In the Julia
+REPL one can access this documentation by entering the help mode with `?`
+
+```@docs
+RegularizedLeastSquares.L1Regularization
+RegularizedLeastSquares.L2Regularization
+RegularizedLeastSquares.L21Regularization
+RegularizedLeastSquares.LLRRegularization
+RegularizedLeastSquares.NuclearRegularization
+RegularizedLeastSquares.TVRegularization
+```
+
+## Projection Regularization
+```@docs
+RegularizedLeastSquares.PositiveRegularization
+RegularizedLeastSquares.RealRegularization
+```
+
+## Nested Regularization
+```@docs
+RegularizedLeastSquares.innerreg(::AbstractNestedRegularization)
+RegularizedLeastSquares.sink(::AbstractNestedRegularization)
+RegularizedLeastSquares.sinktype(::AbstractNestedRegularization)
+```
+
+## Scaled Regularization
+```@docs
+RegularizedLeastSquares.AbstractScaledRegularization
+RegularizedLeastSquares.scalefactor
+RegularizedLeastSquares.NormalizedRegularization
+RegularizedLeastSquares.NoNormalization
+RegularizedLeastSquares.MeasurementBasedNormalization
+RegularizedLeastSquares.SystemMatrixBasedNormalization
+RegularizedLeastSquares.FixedParameterRegularization
+```
+
+## Misc. Nested Regularization
+```@docs
+RegularizedLeastSquares.MaskedRegularization
+RegularizedLeastSquares.TransformedRegularization
+RegularizedLeastSquares.PlugAndPlayRegularization
+```
+
+## Miscellaneous Functions
+```@docs
+RegularizedLeastSquares.prox!(::AbstractParameterizedRegularization, ::AbstractArray)
+RegularizedLeastSquares.prox!(::Type{<:AbstractParameterizedRegularization}, ::Any, ::Any)
+RegularizedLeastSquares.norm(::AbstractParameterizedRegularization, ::AbstractArray)
+RegularizedLeastSquares.λ(::AbstractParameterizedRegularization)
+RegularizedLeastSquares.norm(::Type{<:AbstractParameterizedRegularization}, ::Any, ::Any)
+```

docs/src/API/plan.md

@@ -0,0 +1,60 @@
+# API for Solvers
+This page contains documentation of the public API of the RegularizedLeastSquares. In the Julia
+REPL one can access this documentation by entering the help mode with `?`
+
+## solve!
+```@docs
+RegularizedLeastSquares.solve!(::AbstractLinearSolver, ::Any)
+RegularizedLeastSquares.init!(::AbstractLinearSolver, ::Any)
+RegularizedLeastSquares.init!(::AbstractLinearSolver, ::AbstractSolverState, ::AbstractMatrix)
+
+```
+
+## ADMM
+```@docs
+RegularizedLeastSquares.ADMM
+```
+
+## CGNR
+```@docs
+RegularizedLeastSquares.CGNR
+```
+
+## Kaczmarz
+```@docs
+RegularizedLeastSquares.Kaczmarz
+```
+
+## FISTA
+```@docs
+RegularizedLeastSquares.FISTA
+```
+
+## OptISTA
+```@docs
+RegularizedLeastSquares.OptISTA
+```
+
+## POGM
+```@docs
+RegularizedLeastSquares.POGM
+```
+
+## SplitBregman
+```@docs
+RegularizedLeastSquares.SplitBregman
+```
+
+## Miscellaneous
+```@docs
+RegularizedLeastSquares.solverstate
+RegularizedLeastSquares.solversolution
+RegularizedLeastSquares.solverconvergence
+RegularizedLeastSquares.StoreSolutionCallback
+RegularizedLeastSquares.StoreConvergenceCallback
+RegularizedLeastSquares.CompareSolutionCallback
+RegularizedLeastSquares.linearSolverList
+RegularizedLeastSquares.createLinearSolver
+RegularizedLeastSquares.applicableSolverList
+RegularizedLeastSquares.isapplicable
+```

docs/src/example_intro.md

@@ -0,0 +1,27 @@
+# Small Reconstruction Package for Radon projections
+In this example we will implement a small image reconstruction package with the help of `AbstractImageReconstruction.jl`. Our example reconstruction package aims to provide direct and iterative reconstruction algorithms for Radon projection data with optional GPU support. 
+
+Most of the desired functionality is already implemented in various Julia packages. Our reconstruction packages now needs to properly connect these packages and transform the data into the appropriate formats for each package.
+
+## Installation
+In addition to AbstractImageReconstruction.jl, we will need a few more packages to get started. We can install these packages using the Julia package manager. Open a Julia REPL and run the following command:
+
+```julia
+using Pkg
+Pkg.add("AbstractImageReconstruction")
+```
+This will download and install AbstractImageReconstruction.jl and its dependencies. To install a different version, please consult the [Pkg documentation](https://pkgdocs.julialang.org/dev/managing-packages/#Adding-packages). 
+
+
+[RadonKA.jl](https://github.com/roflmaostc/RadonKA.jl/tree/main) provides us with fast Radon forward and backprojections, which we can use for direct reconstructions and preparing example data for our package. 
+
+[LinearOperatorCollection.jl](https://github.com/JuliaImageRecon/LinearOperatorCollection.jl) wraps the functionality of RadonKA.jl in a matrix-free linear operator, which can be used in iterative solvers.
+
+[RegularizedLeastSquares.jl](https://github.com/JuliaImageRecon/RegularizedLeastSquares.jl) offers a variety of iterative solver and regularization options.
+
+[ImagePhantoms.jl](https://github.com/JuliaImageRecon/ImagePhantoms.jl) and [ImageGeoms.jl](https://github.com/JuliaImageRecon/ImageGeoms.jl) allow us to define digital software "phantoms", which we will use to test our reconstruction algorithms.
+
+Lastly, we will use [CairoMakie.jl](https://docs.makie.org/stable/) to visualize our results.
+
+## Outline
+

docs/src/index.md

@@ -0,0 +1,47 @@
+# AbstractImageReconstruction.jl
+
+*Abstract Interface for Medical Image Reconstruction Packages*
+
+## Introduction
+
+AbstractImageReconstruction.jl is a Julia package that serves as the core API for medical imaging packages. It provides implementations an interface and type hierarchy with which one can represent and implement image reconstruction algorithms, their parameters and runtime behaviour. In particular, this package serves as the API of the Julia packages [MPIReco.jl](https://github.com/MagneticParticleImaging/MPIReco.jl).
+
+## Features
+
+* Variety of optimization algorithms optimized for least squares problems
+* Storing, loading and manipulating of reconstruction algorithms with (partially) set parameters
+* Attaching callback listeners to parameters
+
+## Installation
+
+Within Julia, use the package manager:
+```julia
+using Pkg
+Pkg.add("AbstractImageReconstruction")
+```
+AbstractImageReconstruction is not intended to be used alone, but together with an image reconstruction package that implements the provided interface, such as [MPIReco.jl](https://github.com/MagneticParticleImaging/MPIReco.jl).
+
+## Usage
+Concrete construction of reconstruction algorithms depend on the implementation of the reconstruction package. Once an algorithms is constructed with the given paramters, images can be reconstructed as follows:
+```julia
+using AbstractImageReconstruction, MPIReco
+
+params = ... # Setup reconstruction paramter
+algo = ... # Setup chosen algorithm with params
+raw = ... # Setup raw data
+
+image = reconstruct(algo, raw)
+```
+Once an algorithm is constructed it can be transformed into a `RecoPlan`. These are mutable and transparent wrappers around the nested types of the algorithm and its paramters, that can be stored and restored to and from TOML files.
+
+```julia
+plan = toPlan(algo)
+savePlan(MPIReco, "Example", plan)
+plan = loadPlan(MPIReco, "Example", [MPIReco, RegularizedLeastSquares, MPIFiles])
+
+algo2 = build(plan)
+algo == algo2 # true
+```
+Unlike concrete algorithm instances, a `RecoPlan` may still be missing certain values of its fields and it can encode the structure of an image reconstruction algorithm without concrete parameterization.
+
+It is also possible to attach `Listeners` to `RecoPlan` fields, that call user-specified functions if they are changed. This allows specific `RecoPlans` to provide smart default paramter choices or embedding a plan into a GUI.