Merge pull request #221 from ArnoStrouwen/docs1

Documenter 1.0 upgrade.

Author: ChrisRackauckas

.JuliaFormatter.toml

@@ -0,0 +1,2 @@
+style = "sciml"
+format_markdown = true

.github/workflows/CI.yml

@@ -3,9 +3,13 @@ on:
   pull_request:
     branches:
       - master
+    paths-ignore:
+      - 'docs/**'
   push:
     branches:
       - master
+    paths-ignore:
+      - 'docs/**'
 jobs:
   test:
     runs-on: ubuntu-latest

.github/workflows/FormatCheck.yml

@@ -0,0 +1,42 @@
+name: format-check
+
+on:
+  push:
+    branches:
+      - 'master'
+      - 'release-'
+    tags: '*'
+  pull_request:
+
+jobs:
+  build:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        julia-version: [1]
+        julia-arch: [x86]
+        os: [ubuntu-latest]
+    steps:
+      - uses: julia-actions/setup-julia@latest
+        with:
+          version: ${{ matrix.julia-version }}
+
+      - uses: actions/checkout@v4
+      - name: Install JuliaFormatter and format
+        # This will use the latest version by default but you can set the version like so:
+        #
+        # julia  -e 'using Pkg; Pkg.add(PackageSpec(name="JuliaFormatter", version="0.13.0"))'
+        run: |
+          julia  -e 'using Pkg; Pkg.add(PackageSpec(name="JuliaFormatter"))'
+          julia  -e 'using JuliaFormatter; format(".", verbose=true)'
+      - name: Format check
+        run: |
+          julia -e '
+          out = Cmd(`git diff --name-only`) |> read |> String
+          if out == ""
+              exit(0)
+          else
+              @error "Some files have not been formatted !!!"
+              write(stdout, out)
+              exit(1)
+          end'

docs/Project.toml

@@ -3,5 +3,5 @@ Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 SciMLOperators = "c0aeaf25-5076-4817-a8d5-81caf7dfa961"
 
 [compat]
-Documenter = "0.27"
+Documenter = "1"
 SciMLOperators = "0.2, 0.3"

docs/make.jl

@@ -9,8 +9,9 @@ makedocs(
     sitename="SciMLOperators.jl",
     authors="Vedant Puri, Alex Jones, Chris Rackauckas",
     modules=[SciMLOperators],
-    clean=true,doctest=false,
-    format = Documenter.HTML(analytics = "UA-90474609-3",
+    clean=true, doctest=false, linkcheck = true,
+    warnonly = [:docs_block, :missing_docs, :cross_references, :linkcheck],
+    format = Documenter.HTML(
                              assets = ["assets/favicon.ico"],
                              canonical="https://docs.sciml.ai/SciMLOperators/stable"),
     pages=pages

docs/src/index.md

@@ -7,22 +7,23 @@ operators, fast tensor-product evaluations, pre-cached mutating
 evaluations, as well as `Zygote`-compatible non-mutating evaluations.
 
 The lazily implemented operator algebra allows the user to update the
-operator state by passing in an update function that accepts arbirary
+operator state by passing in an update function that accepts arbitrary
 parameter objects. Further, our operators behave like `AbstractMatrix` types
-thanks to  overloads defined for methods in `Base`, and `LinearAlgebra`.
+thanks to overloads defined for methods in `Base`, and `LinearAlgebra`.
 
 Therefore, an `AbstractSciMLOperator` can be passed to `LinearSolve.jl`,
-or `NonlinearSolve.jl` as a linear/nonlinear operator, or to
+or `NonlinearSolve.jl` as a linear or nonlinear operator, or to
 `OrdinaryDiffEq.jl` as an `ODEFunction`. Examples of usage within the
 `SciML` ecosystem are provided in the documentation.
 
+
 ## Installation
-`SciMLOperators.jl` is a registerd package and can be installed via
 
-```
-julia> import Pkg
-julia> Pkg.add("SciMLOperators")
-```
+To install SciMLOperators.jl, use the Julia package manager:
+
+```julia
+using Pkg
+Pkg.add("SciMLOperators")
 
 ## Examples
 
@@ -61,8 +62,8 @@ u_kron = rand(N ^ 3)
 v_kron = L3(u_kron, p, t) # == L3 * u_kron
 ```
 
-For mutating operator evaluations, call `cache_operator` to generate
-in-place cache so the operation is nonallocating.
+For mutating operator evaluations, call `cache_operator` to generate an
+in-place cache, so the operation is nonallocating.
 
 ```julia
 α, β = rand(2)
@@ -76,7 +77,7 @@ L2(v, u, p, t) # == mul!(v, L2, u)
 L4(v, u, p, t, α, β) # == mul!(v, L4, u, α, β)
 ```
 
-The calling signature `L(u, p, t)`, for out-of-place evaluations is
+The calling signature `L(u, p, t)`, for out-of-place evaluations, is
 equivalent to `L * u`, and the in-place evaluation `L(v, u, p, t, args...)`
 is equivalent to `LinearAlgebra.mul!(v, L, u, args...)`, where the arguments
 `p, t` are passed to `L` to update its state. More details are provided
@@ -95,75 +96,82 @@ object `p`.
 
 * Matrix-free operators with `FunctionOperator`
 * Fast tensor product evaluation with `TensorProductOperator`
-* Lazy algebra: addition, subtraction, multiplication, inverse, adjoint, transpose
+* Lazy algebra: addition, subtraction, multiplication, inverse, adjoint, and transpose
 * Couple fast methods for operator evaluation with inversion via `InvertibleOperator`
 * One-line API to update operator state depending on arbitrary parameters.
-* Mutating, nonmutating update behaviour (Zygote compatible)
-* One-line API to pre-caching operators for in-place operator evaluations
+* Mutating and nonmutating update behavior (Zygote compatible)
+* One-line API for pre-caching operators for in-place operator evaluations
 
 ## Contributing
 
-- Please refer to the
-  [SciML ColPrac: Contributor's Guide on Collaborative Practices for Community Packages](https://github.com/SciML/ColPrac/blob/master/README.md)
-  for guidance on PRs, issues, and other matters relating to contributing to SciML.
-- There are a few community forums:
-    - The #diffeq-bridged and #sciml-bridged channels in the
-      [Julia Slack](https://julialang.org/slack/)
-    - [JuliaDiffEq](https://gitter.im/JuliaDiffEq/Lobby) on Gitter
-    - On the Julia Discourse forums (look for the [modelingtoolkit tag](https://discourse.julialang.org/tag/modelingtoolkit)
-    - See also [SciML Community page](https://sciml.ai/community/)
+  - Please refer to the
+    [SciML ColPrac: Contributor's Guide on Collaborative Practices for Community Packages](https://github.com/SciML/ColPrac/blob/master/README.md)
+    for guidance on PRs, issues, and other matters relating to contributing to SciML.
+
+  - See the [SciML Style Guide](https://github.com/SciML/SciMLStyle) for common coding practices and other style decisions.
+  - There are a few community forums:
+    
+      + The #diffeq-bridged and #sciml-bridged channels in the
+        [Julia Slack](https://julialang.org/slack/)
+      + The #diffeq-bridged and #sciml-bridged channels in the
+        [Julia Zulip](https://julialang.zulipchat.com/#narrow/stream/279055-sciml-bridged)
+      + On the [Julia Discourse forums](https://discourse.julialang.org)
+      + See also [SciML Community page](https://sciml.ai/community/)
 
 ## Reproducibility
+
 ```@raw html
 <details><summary>The documentation of this SciML package was built using these direct dependencies,</summary>
 ```
+
 ```@example
 using Pkg # hide
 Pkg.status() # hide
 ```
+
 ```@raw html
 </details>
 ```
+
 ```@raw html
 <details><summary>and using this machine and Julia version.</summary>
 ```
+
 ```@example
 using InteractiveUtils # hide
 versioninfo() # hide
 ```
+
 ```@raw html
 </details>
 ```
+
 ```@raw html
 <details><summary>A more complete overview of all dependencies and their versions is also provided.</summary>
 ```
+
 ```@example
 using Pkg # hide
-Pkg.status(;mode = PKGMODE_MANIFEST) # hide
+Pkg.status(; mode = PKGMODE_MANIFEST) # hide
 ```
+
 ```@raw html
 </details>
 ```
-```@raw html
-You can also download the 
-<a href="
-```
-```@eval
-using TOML
-version = TOML.parse(read("../../Project.toml",String))["version"]
-name = TOML.parse(read("../../Project.toml",String))["name"]
-link = "https://github.com/SciML/"*name*".jl/tree/gh-pages/v"*version*"/assets/Manifest.toml"
-```
-```@raw html
-">manifest</a> file and the
-<a href="
-```
+
 ```@eval
 using TOML
-version = TOML.parse(read("../../Project.toml",String))["version"]
-name = TOML.parse(read("../../Project.toml",String))["name"]
-link = "https://github.com/SciML/"*name*".jl/tree/gh-pages/v"*version*"/assets/Project.toml"
-```
-```@raw html
-">project</a> file.
+using Markdown
+version = TOML.parse(read("../../Project.toml", String))["version"]
+name = TOML.parse(read("../../Project.toml", String))["name"]
+link_manifest = "https://github.com/SciML/" * name * ".jl/tree/gh-pages/v" * version *
+                "/assets/Manifest.toml"
+link_project = "https://github.com/SciML/" * name * ".jl/tree/gh-pages/v" * version *
+               "/assets/Project.toml"
+Markdown.parse("""You can also download the
+[manifest]($link_manifest)
+file and the
+[project]($link_project)
+file.
+""")
 ```

docs/src/interface.md

@@ -5,14 +5,14 @@
 These are the formal properties that an `AbstractSciMLOperator` should obey
 for it to work in the solvers.
 
-1. An `AbstractSciMLOperator` represents a linear or nonlinear operator with input/output
-   being `AbstractArray`s. Specifically, a SciMLOperator, `L`, of size `(M, N)` accepts
+1. An `AbstractSciMLOperator` represents a linear or nonlinear operator, with input/output
+   being `AbstractArray`s. Specifically, a SciMLOperator, `L`, of size `(M, N)` accepts an
    input argument `u` with leading length `N`, i.e. `size(u, 1) == N`, and returns an
    `AbstractArray` of the same dimension with leading length `M`, i.e. `size(L * u, 1) == M`.
 2. SciMLOperators can be applied to an `AbstractArray` via overloaded `Base.*`, or
    the in-place `LinearAlgebra.mul!`. Additionally, operators are allowed to be time,
    or parameter dependent. The state of a SciMLOperator can be updated by calling
-   the mutating function `update_coefficients!(L, u, p, t)` where `p` representes
+   the mutating function `update_coefficients!(L, u, p, t)` where `p` represents
    parameters, and `t`, time.  Calling a SciMLOperator as `L(du, u, p, t)` or out-of-place
    `L(u, p, t)` will automatically update the state of `L` before applying it to `u`.
    `L(u, p, t)` is the same operation as `L(u, p, t) * u`.
@@ -25,11 +25,11 @@ for it to work in the solvers.
 ## Overloaded Traits
 
 Thanks to overloads defined for evaluation methods and traits in
-`Base`, `LinearAlgebra`, the behaviour of a `SciMLOperator` is
+`Base`, `LinearAlgebra`, the behavior of a `SciMLOperator` is
 indistinguishable from an `AbstractMatrix`. These operators can be
 passed to linear solver packages, and even to ordinary differential
 equation solvers. The list of overloads to the `AbstractMatrix`
-interface include, but are not limited, the following:
+interface includes, but is not limited to, the following:
 
 - `Base: size, zero, one, +, -, *, /, \, ∘, inv, adjoint, transpose, convert`
 - `LinearAlgebra: mul!, ldiv!, lmul!, rmul!, factorize, issymmetric, ishermitian, isposdef`
@@ -94,13 +94,13 @@ L(u, p, t) != zeros(N) # true
 The out-of-place evaluation function `L(u, p, t)` calls
 `update_coefficients` under the hood, which recursively calls
 the `update_func` for each component `SciMLOperator`.
-Therefore the out-of-place evaluation function is equivalent to
+Therefore, the out-of-place evaluation function is equivalent to
 calling `update_coefficients` followed by `Base.*`. Notice that
 the out-of-place evaluation does not return the updated operator.
 
-On the other hand,, the in-place evaluation function, `L(v, u, p, t)`,
+On the other hand, the in-place evaluation function, `L(v, u, p, t)`,
 mutates `L`, and is equivalent to calling `update_coefficients!`
-followed by `mul!`. The in-place update behaviour works the same way
+followed by `mul!`. The in-place update behavior works the same way,
 with a few `<!>`s appended here and there. For example,
 
 ```julia
@@ -133,11 +133,11 @@ mul!(v, u, p, t) != zero(N) # true
 L(v, u, p, t) != zero(N) # true
 ```
 
-The update behaviour makes this package flexible enough to be used
+The update behavior makes this package flexible enough to be used
 in `OrdianryDiffEq`. As the parameter object `p` is often reserved
-for sensitivy computation via automatic-differentiation, a user may
+for sensitivity computation via automatic-differentiation, a user may
 prefer to pass in state information via other arguments. For that
-reason, we allow for update functions with arbitrary keyword arguments.
+reason, we allow update functions with arbitrary keyword arguments.
 
 ```julia
 mat_update_func = (A, u, p, t; scale = 0.0) -> scale * (p * p')
@@ -178,24 +178,24 @@ has_ldiv!
 
 ## Note About Affine Operators
 
-Affine operators are operators which have the action `Q*x = A*x + b`. These operators have
-no matrix representation, since if there was it would be a linear operator instead of an 
+Affine operators are operators that have the action `Q*x = A*x + b`. These operators have
+no matrix representation, since if there was, it would be a linear operator instead of an 
 affine operator. You can only represent an affine operator as a linear operator in a 
 dimension of one larger via the operation: `[A b] * [u;1]`, so it would require something modified 
 to the input as well. As such, affine operators are a distinct generalization of linear operators.
 
-While it this seems like it might doom the idea of using matrix-free affine operators, it turns out 
+While it seems like it might doom the idea of using matrix-free affine operators, it turns out 
 that affine operators can be used in all cases where matrix-free linear solvers are used due to
-an easy genearlization of the standard convergence proofs. If Q is the affine operator 
+an easy generalization of the standard convergence proofs. If Q is the affine operator 
 ``Q(x) = Ax + b``, then solving ``Qx = c`` is equivalent to solving ``Ax + b = c`` or ``Ax = c-b``. 
-If you know do this same "plug-and-chug" handling of the affine operator in into the GMRES/CG/etc. 
+If you now do this same “plug-and-chug” handling of the affine operator into the GMRES/CG/etc. 
 convergence proofs, move the affine part to the rhs residual, and show it converges to solving 
 ``Ax = c-b``, and thus GMRES/CG/etc. solves ``Q(x) = c`` for an affine operator properly. 
 
-That same trick then can be used pretty much anywhere you would've had a linear operator to extend 
+That same trick can be used mostly anywhere you would've had a linear operator to extend 
 the proof to affine operators, so then ``exp(A*t)*v`` operations via Krylov methods work for A being 
-affine as well, and all sorts of things. Thus affine operators have no matrix representation but they 
-are still compatible with essentially any Krylov method which would otherwise be compatible with
+affine as well, and all sorts of things. Thus, affine operators have no matrix representation, but they 
+are still compatible with essentially any Krylov method, which would otherwise be compatible with
 matrix-free representations, hence their support in the SciMLOperators interface.
 
 ## Note about keyword arguments to `update_coefficients!`