Fix doc build (#12)

Author: vchuravy

.github/workflows/Documentation.yml

@@ -5,20 +5,26 @@ on:
     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@v2
-      - uses: julia-actions/setup-julia@v1
+      - 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.develop(PackageSpec(path=pwd()))
             Pkg.instantiate()
           '
       - name: run doctests

docs/Project.toml

@@ -6,4 +6,8 @@ Krylov = "ba0b0d4f-ebba-5204-a429-3ac8c609bfb7"
 KrylovPreconditioners = "45d422c2-293f-44ce-8315-2cb988662dec"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
+NewtonKrylov = "0be81120-40bf-4f8b-adf0-26103efb66f1"
 SparseArrays = "2f01184e-e22b-5df5-ae63-d93ebab69eaf"
+
+[sources.NewtonKrylov]
+path = ".."

src/NewtonKrylov.jl

@@ -19,6 +19,11 @@ function maybe_duplicated(f, df)
     end
 end
 
+"""
+    JacobianOperator
+
+Efficient implementation of `J(f,x) * v` and `v * J(f, x)'`
+"""
 struct JacobianOperator{F, A}
     f::F # F!(res, u)
     f_cache::F
@@ -89,7 +94,22 @@ end
 ##
 import Base: @kwdef
 
+"""
+    Forcing
+
+Implements forcing for inexact Newton-Krylov.
+The equation ``‖F′(u)d + F(u)‖ <= η * ‖F(u)‖`` gives
+the inexact Newton termination criterion.
+
+## Implemented variants
+- [`Fixed`](@ref)
+- [`EisenstatWalker`](@ref)
+"""
 abstract type Forcing end
+
+"""
+    Fixed(η = 0.1)
+"""
 @kwdef struct Fixed <: Forcing
     η::Float64 = 0.1
 end
@@ -99,6 +119,9 @@ function (F::Fixed)(args...)
 end
 inital(F::Fixed) = F.η
 
+"""
+    EisenstatWalker(η_max = 0.999, γ = 0.9)
+"""
 @kwdef struct EisenstatWalker <: Forcing
     η_max::Float64 = 0.999
     γ::Float64 = 0.9
@@ -121,11 +144,44 @@ function (F::EisenstatWalker)(η, tol, n_res, n_res_prior)
 end
 inital(F::EisenstatWalker) = F.η_max
 
+const KWARGS_DOCS = """
+## Keyword Arguments
+  - `tol_rel`: Relative tolerance
+  - `tol_abs`: Absolute tolerance
+  - `max_niter`: Maximum number of iterations
+  - `forcing`: Maximum forcing term for inexact Newton.
+             If `nothing` an exact Newton method is used.  
+  - `verbose`:
+  - `Solver`:
+  - `M`:
+  - `N`:
+  - `krylov_kwarg`
+  - `callback`:
+"""
+
+"""
+    newton_krylov(F, u₀::AbstractArray, M::Int = length(u₀); kwargs...)
+
+## Arguments
+  - `F`: `res = F(u₀)` solves `res = F(u₀) = 0`
+  - `u₀`: Initial guess
+  - `M`: Length of the output of `F`. Defaults to `length(u₀)`.
+  
+$(KWARGS_DOCS)
+"""
 function newton_krylov(F, u₀::AbstractArray, M::Int = length(u₀); kwargs...)
     F!(res, u) = (res .= F(u); nothing)
     return newton_krylov!(F!, u₀, M; kwargs...)
 end
 
+"""
+## Arguments
+  - `F!`: `F!(res, u)` solves `res = F(u) = 0`
+  - `u₀`: Initial guess
+  - `M`: Length of  the output of `F!`. Defaults to `length(u₀)`
+
+$(KWARGS_DOCS)
+"""
 function newton_krylov!(F!, u₀::AbstractArray, M::Int = length(u₀); kwargs...)
     res = similar(u₀, M)
     return newton_krylov!(F!, u₀, res; kwargs...)
@@ -148,12 +204,8 @@ end
   - `F!`: `F!(res, u)` solves `res = F(u) = 0`
   - `u`: Initial guess
   - `res`: Temporary for residual
-## Keyword Arguments
-  - `tol_rel`: Relative tolerance
-  - `tol_abs`: Absolute tolerance
-  - `max_niter`: Maximum number of iterations
-  - `forcing`: Maximum forcing term for inexact Newton.
-             If `nothing` an exact Newton method is used.   
+ 
+$(KWARGS_DOCS)
 """
 function newton_krylov!(
         F!, u::AbstractArray, res::AbstractArray;

test/Project.toml

@@ -2,3 +2,7 @@
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 Enzyme = "7da242da-08ed-463a-9acd-ee780be4f1d9"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
+NewtonKrylov = "0be81120-40bf-4f8b-adf0-26103efb66f1"
+
+[sources.NewtonKrylov]
+path = ".."