Skip to content

Fix docstring warnings and remove warnonly from makedocs (#378) #909

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Kk-304 wants to merge 1 commit into
base: main
Choose a base branch
from
+142 −22
Open

Fix docstring warnings and remove warnonly from makedocs (#378) #909

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 1 addition & 2 deletions docs/make.jl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,9 +11,8 @@ include("pages.jl")
makedocs(
sitename = "LinearSolve.jl",
authors = "Chris Rackauckas",
modules = [LinearSolve, LinearSolve.SciMLBase],
modules = [LinearSolve],
clean = true, doctest = false, linkcheck = true,
warnonly = [:docs_block, :missing_docs],
linkcheck_ignore = [
"https://cli.github.com/manual/installation",
],
Expand Down
24 changes: 20 additions & 4 deletions docs/src/advanced/internal_api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -107,6 +107,7 @@ These trait functions help determine algorithm capabilities and requirements:

```@docs
LinearSolve.needs_concrete_A
LinearSolve.needs_square_A
```

## Utility Functions
Expand All @@ -122,11 +123,10 @@ LinearSolve.__init_u0_from_Ab

## Solve Functions

For custom solving strategies:
The default solver dispatch and adjoint evaluation internals:

```@docs
LinearSolve.LinearSolveFunction
LinearSolve.DirectLdiv!
LinearSolve.defaultalg_adjoint_eval
```

## Preconditioner Infrastructure
Expand All @@ -143,10 +143,26 @@ LinearSolve.InvPreconditioner
These are internal algorithm implementations:

```@docs
LinearSolve.SimpleLUFactorization
LinearSolve.LUSolver
```

## BLAS Logging Internals

The BLAS logging system provides diagnostic information about BLAS operations:

```@docs
LinearSolve.BlasOperationInfo
LinearSolve.interpret_blas_code
LinearSolve.blas_info_msg
LinearSolve._format_blas_context
```

## SimpleGMRES Internals

```@docs
LinearSolve._sym_givens
```

## Developer Notes

### Adding New Algorithms
Expand Down
11 changes: 11 additions & 0 deletions docs/src/assets/Project.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
[deps]
Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
LinearSolve = "7ed4a6bd-45f5-4d41-b270-4a48e9bafcae"
LinearSolveAutotune = "67398393-80e8-4254-b7e4-1b9a36a3c5b6"
SciMLOperators = "c0aeaf25-5076-4817-a8d5-81caf7dfa961"

[compat]
Documenter = "1"
LinearSolve = "3"
LinearSolveAutotune = "1.1"
SciMLOperators = "1"
47 changes: 47 additions & 0 deletions docs/src/solvers/solvers.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -130,6 +130,8 @@ LinearSolve.DefaultLinearSolver

```@docs
RFLUFactorization
ButterflyFactorization
RF32MixedLUFactorization
```

### Base.LinearAlgebra
Expand All @@ -142,9 +144,11 @@ customized per-package, details given below describe a subset of important array
```@docs
LUFactorization
GenericLUFactorization
GenericFactorization
QRFactorization
SVDFactorization
CholeskyFactorization
LDLtFactorization
BunchKaufmanFactorization
CHOLMODFactorization
NormalCholeskyFactorization
Expand Down Expand Up @@ -232,7 +236,9 @@ CliqueTreesFactorization
```@docs
KrylovJL_CG
KrylovJL_MINRES
KrylovJL_MINARES
KrylovJL_GMRES
KrylovJL_FGMRES
KrylovJL_BICGSTAB
KrylovJL_LSMR
KrylovJL_CRAIGMR
Expand All @@ -250,6 +256,7 @@ MKL32MixedLUFactorization

```@docs
OpenBLASLUFactorization
OpenBLAS32MixedLUFactorization
```

### AppleAccelerate.jl
Expand Down Expand Up @@ -283,6 +290,8 @@ MetalOffload32MixedLUFactorization
```@docs
MKLPardisoFactorize
MKLPardisoIterate
PanuaPardisoFactorize
PanuaPardisoIterate
LinearSolve.PardisoJL
```

Expand All @@ -296,6 +305,7 @@ The following are non-standard GPU factorization routines.
Using these solvers requires adding the package CUDA.jl, i.e. `using CUDA`

```@docs
CudaOffloadFactorization
CudaOffloadLUFactorization
CudaOffloadQRFactorization
CUDAOffload32MixedLUFactorization
Expand Down Expand Up @@ -362,6 +372,37 @@ KrylovKitJL
HYPREAlgorithm
```

### BLIS

!!! note

Using this solver requires adding the packages blis_jll and LAPACK_jll, i.e. `using blis_jll, LAPACK_jll`
Comment on lines +375 to +379
Copy link

Copilot AI Mar 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These new @docs blocks reference solvers that (per the notes) require optional packages/JLLs. With warnonly removed, docs will now hard-fail if these symbols aren’t defined/loaded during documentation build (common when solver types are provided via package extensions that only activate when the dependency is in the docs environment). Consider ensuring the docs environment includes the needed optional deps (e.g., blis_jll, LAPACK_jll, AlgebraicMultigrid, PETSc, possibly SparseArrays where relevant), or conditionally including these @docs blocks only when the dependency is available.

Copilot uses AI. Check for mistakes.

```@docs
LinearSolve.BLISLUFactorization
```

### AlgebraicMultigrid.jl

!!! note

Using this solver requires adding the package AlgebraicMultigrid.jl, i.e. `using AlgebraicMultigrid`

```@docs
AlgebraicMultigridJL
```

### PETSc.jl

!!! note

Using PETSc solvers requires Julia version 1.10 or higher, and that the packages
PETSc.jl and SparseArrays.jl are loaded.

```@docs
PETScAlgorithm
```

### Ginkgo.jl

!!! note
Expand All @@ -374,3 +415,9 @@ GinkgoJL
GinkgoJL_CG
GinkgoJL_GMRES
```

### Sensitivity / Adjoint

```@docs
LinearSolveAdjoint
```
Binary file added docs_build.log
View file
Open in desktop
Copy link
Copy Markdown
Member

@ChrisRackauckas ChrisRackauckas Mar 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

?

Binary file not shown.
31 changes: 31 additions & 0 deletions src/LinearSolve.jl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -96,6 +96,37 @@ end

@reexport using SciMLBase

# Attach LinearProblem docstring to LinearSolve module for Documenter.jl
# (LinearProblem is defined in SciMLBase but reexported here)
@doc """
LinearProblem(A, b; u0 = nothing, p = nothing)
Comment on lines +99 to +102
Copy link
Copy Markdown
Member

@ChrisRackauckas ChrisRackauckas Mar 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No this is piracy

LinearProblem{iip}(A, b; u0 = nothing, p = nothing)

Define a linear system problem ``Au = b``.

## Arguments

- `A`: The coefficient matrix or linear operator. Can be a dense matrix, sparse matrix,
or any `AbstractSciMLOperator`.
- `b`: The right-hand side vector.
- `u0`: (optional) Initial guess for iterative solvers. Defaults to `nothing`.
- `p`: (optional) Parameters for the problem. Defaults to `nothing`.

## Example
Comment on lines +101 to +115
Copy link

Copilot AI Mar 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This introduces a new external link while docs/make.jl has linkcheck = true. External link checks can be flaky in CI (network/DNS/transient outages), which becomes more painful now that doc warnings are no longer ignored. Consider adding https://docs.sciml.ai/SciMLBase/stable/ to linkcheck_ignore, or switching to a non-linkchecked reference pattern if the project prefers strict linkchecking.

Copilot uses AI. Check for mistakes.

```julia
using LinearSolve

A = [1.0 2.0; 3.0 4.0]
b = [5.0, 6.0]
prob = LinearProblem(A, b)
sol = solve(prob)
sol.u # solution vector
```

For more details, see the [SciMLBase LinearProblem documentation](https://docs.sciml.ai/SciMLBase/stable/).
""" LinearProblem

"""
SciMLLinearSolveAlgorithm <: SciMLBase.AbstractLinearAlgorithm

Expand Down
27 changes: 11 additions & 16 deletions src/default.jl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -118,8 +118,6 @@ This function is primarily used internally by `solve(::LinearProblem)` when no
explicit algorithm is provided. For manual algorithm selection, users can
directly instantiate specific algorithm types.
"""
# Legacy fallback
# For SciML algorithms already using `defaultalg`, all assume square matrix.
defaultalg(A, b) = defaultalg(A, b, OperatorAssumptions(true))

function defaultalg(
Expand Down Expand Up @@ -562,13 +560,8 @@ defaultalg_symbol(::Type{<:GenericFactorization{typeof(ldlt!)}}) = :LDLtFactoriz

defaultalg_symbol(::Type{<:QRFactorization{ColumnNorm}}) = :QRFactorizationPivoted

"""
if alg.alg === DefaultAlgorithmChoice.LUFactorization
SciMLBase.solve!(cache, LUFactorization(), args...; kwargs...))
else
...
end
"""
# Generated dispatch: routes to the specific solver based on alg.alg,
# with automatic fallback to column-pivoted QR when LU factorization fails.
@generated function SciMLBase.solve!(
cache::LinearCache, alg::DefaultLinearSolver,
args...;
Expand Down Expand Up @@ -814,13 +807,15 @@ end
end

"""
```
elseif DefaultAlgorithmChoice.LUFactorization === cache.alg
(cache.cacheval.LUFactorization)' \\ dy
else
...
end
```
defaultalg_adjoint_eval(cache::LinearCache, dy)

Generated function that dispatches the adjoint (transpose) linear solve for the
default solver polyalgorithm. Given the cached factorization from the forward
solve, computes `A' \\ dy` using the appropriate factorization stored in
`cache.cacheval`.

This is used internally by the adjoint rule for `LinearSolve` to compute
sensitivities efficiently.
"""
@generated function defaultalg_adjoint_eval(cache::LinearCache, dy)
ex = :()
Expand Down
21 changes: 21 additions & 0 deletions src/factorization.jl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -498,6 +498,27 @@ end

## LDLtFactorization

"""
LDLtFactorization(shift = 0.0, perm = nothing)

A wrapper around `LinearAlgebra.ldlt!` for `LDLt` factorization of symmetric
(or Hermitian) positive semi-definite tridiagonal matrices (e.g. `SymTridiagonal`).

## Keyword Arguments

- `shift`: Diagonal shift applied before factoring. Defaults to `0.0`.
- `perm`: Optional permutation vector. Defaults to `nothing`.

Comment on lines +501 to +511
Copy link

Copilot AI Mar 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The docstring documents a keyword-style constructor (LDLtFactorization(shift = ..., perm = ...)), but the shown definition is a plain struct (no Base.@kwdef / explicit keyword outer constructor visible here). If callers can’t actually use keyword construction, this docstring will be misleading and (now that docs are strict) may cause doctest/examples drift. Consider either (a) adding an explicit keyword constructor (or Base.@kwdef if appropriate for this codebase), or (b) updating the signature + “Keyword Arguments” section to match the actual constructor(s).

Copilot uses AI. Check for mistakes.
## Example

```julia
using LinearSolve, LinearAlgebra
A = SymTridiagonal([4.0, 5.0, 6.0], [1.0, 2.0])
b = [1.0, 2.0, 3.0]
prob = LinearProblem(A, b)
sol = solve(prob, LDLtFactorization())
```
"""
struct LDLtFactorization{T} <: AbstractDenseFactorization
shift::Float64
perm::T
Comment on lines 522 to 524
Copy link

Copilot AI Mar 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The docstring documents a keyword-style constructor (LDLtFactorization(shift = ..., perm = ...)), but the shown definition is a plain struct (no Base.@kwdef / explicit keyword outer constructor visible here). If callers can’t actually use keyword construction, this docstring will be misleading and (now that docs are strict) may cause doctest/examples drift. Consider either (a) adding an explicit keyword constructor (or Base.@kwdef if appropriate for this codebase), or (b) updating the signature + “Keyword Arguments” section to match the actual constructor(s).

Copilot uses AI. Check for mistakes.
Expand Down
Loading