Merge pull request #7 from SciML/docs

ChrisRackauckas · web-flow · commit 79a1a3ab0d87 · 2022-06-05T06:15:55.000-04:00
add docs and patch bump
diff --git a/.github/workflows/Documentation.yml b/.github/workflows/Documentation.yml
@@ -0,0 +1,26 @@
+
+name: Documentation
+
+on:
+  push:
+    branches:
+      - master
+      - 'release-'
+    tags: '*'
+  pull_request:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: julia-actions/setup-julia@latest
+        with:
+          version: '1'
+      - name: Install dependencies
+        run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
+      - name: Build and deploy
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # For authentication with GitHub Actions token
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # For authentication with SSH deploy key
+        run: julia --project=docs/ docs/make.jl
diff --git a/.github/workflows/Downstream.yml b/.github/workflows/Downstream.yml
@@ -0,0 +1,51 @@
+name: IntegrationTest
+on:
+  push:
+    branches: [main]
+    tags: [v*]
+  pull_request:
+
+jobs:
+  test:
+    name: ${{ matrix.package.repo }}/${{ matrix.package.group }}/${{ matrix.julia-version }}
+    runs-on: ${{ matrix.os }}
+    env:
+      GROUP: ${{ matrix.package.group }}
+    strategy:
+      matrix:
+        julia-version: [1,1.6]
+        os: [ubuntu-latest]
+        package:
+          - {user: SciML, repo: OrdinaryDiffEq.jl, group: InterfaceI}
+          - {user: SciML, repo: SciMLBase.jl, group: Core}
+          - {user: SciML, repo: DiffEqBase.jl, group: Core}
+
+    steps:
+      - uses: actions/checkout@v2
+      - uses: julia-actions/setup-julia@v1
+        with:
+          version: ${{ matrix.julia-version }}
+          arch: x64
+      - uses: julia-actions/julia-buildpkg@latest
+      - name: Clone Downstream
+        uses: actions/checkout@v2
+        with:
+          repository: ${{ matrix.package.user }}/${{ matrix.package.repo }}
+          path: downstream
+      - name: Load this and run the downstream tests
+        shell: julia --color=yes --project=downstream {0}
+        run: |
+          using Pkg
+          try
+            # force it to use this PR's version of the package
+            Pkg.develop(PackageSpec(path="."))  # resolver may fail with main deps
+            Pkg.update()
+            Pkg.test()  # resolver may fail with test time deps
+          catch err
+            err isa Pkg.Resolve.ResolverError || rethrow()
+            # If we can't resolve that means this is incompatible by SemVer and this is fine
+            # It means we marked this as a breaking change, so we don't need to worry about
+            # Mistakenly introducing a breaking change, as we have intentionally made one
+            @info "Not compatible with this release. No problem." exception=err
+            exit(0)  # Exit immediately, as a success
+          end
diff --git a/Project.toml b/Project.toml
@@ -1,7 +1,7 @@
 name = "CommonSolve"
 uuid = "38540f10-b2f7-11e9-35d8-d573e4eb0ff2"
 authors = ["Chris Rackauckas <accounts@chrisrackauckas.com>"]
-version = "0.2.0"
+version = "0.2.1"
 
 [compat]
 julia = "1.6"
diff --git a/README.md b/README.md
@@ -2,10 +2,10 @@
 
 [![Build Status](https://github.com/SciML/CommonSolve.jl/workflows/CI/badge.svg)](https://github.com/SciML/CommonSolve.jl/actions?query=workflow%3ACI)
 
-This holds the common `solve` command. The rules are that you must dispatch
-on one of your own types. That's it. No pirates.
-
-Oh and there're `init` and `solve!` as well.
+This holds the common `solve`, `init`, and `solve!` commands. By using the same definition,
+solver libraries from other completely different ecosystems can extend the functions and thus
+not clash with SciML if both ecosystems export the `solve` command. The rules are that 
+you must dispatch on one of your own types. That's it. No pirates.
 
 ## General recommendation
 
diff --git a/docs/.gitignore b/docs/.gitignore
@@ -0,0 +1,2 @@
+build/
+site/
diff --git a/docs/Project.toml b/docs/Project.toml
@@ -0,0 +1,5 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+
+[compat]
+Documenter = "0.27"
diff --git a/docs/make.jl b/docs/make.jl
@@ -0,0 +1,19 @@
+using Documenter, CommonSolve
+
+include("pages.jl")
+
+makedocs(
+    sitename="CommonSolve.jl",
+    authors="Chris Rackauckas",
+    modules=[CommonSolve],
+    clean=true,doctest=false,
+    format = Documenter.HTML(analytics = "UA-90474609-3",
+                             assets = ["assets/favicon.ico"],
+                             canonical="https://commonsolve.sciml.ai/stable/"),
+    pages=pages
+)
+
+deploydocs(
+   repo = "github.com/SciML/CommonSolve.jl.git";
+   push_preview = true
+)
diff --git a/docs/pages.jl b/docs/pages.jl
@@ -0,0 +1,3 @@
+pages = [
+        "The Common Solve Interface" => "index.md",
+]
diff --git a/docs/src/assets/favicon.ico b/docs/src/assets/favicon.ico
diff --git a/docs/src/assets/logo.png b/docs/src/assets/logo.png
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -0,0 +1,52 @@
+# CommonSolve.jl: The Common Solve Definition and Interface
+
+This holds the common `solve`, `init`, and `solve!` commands. By using the same definition,
+solver libraries from other completely different ecosystems can extend the functions and thus
+not clash with SciML if both ecosystems export the `solve` command. The rules are that 
+you must dispatch on one of your own types. That's it. No pirates.
+
+## General recommendation
+
+`solve` function has the default definition
+
+```julia
+solve(args...; kwargs...) = solve!(init(args...; kwargs...))
+```
+
+So, we recommend defining
+
+```julia
+init(::ProblemType, args...; kwargs...) :: SolverType
+solve!(::SolverType) :: SolutionType
+```
+
+where `ProblemType`, `SolverType`, and `SolutionType` are the types defined in
+your package.
+
+To avoid method ambiguity, the first argument of `solve`, `solve!`, and `init`
+_must_ be dispatched on the type defined in your package.  For example, do
+_not_ define a method such as
+
+```julia
+init(::AbstractVector, ::AlgorithmType)
+```
+
+## API
+
+```@docs
+init
+solve
+solve!
+```
+
+## 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/)
diff --git a/src/CommonSolve.jl b/src/CommonSolve.jl
@@ -1,7 +1,61 @@
 module CommonSolve
 
+"""
+```julia
+CommonSolve.solve(args...; kwargs...)
+```
+
+Solves an equation or other mathematical problem using the algorithm
+specified in the arguments. Generally, the interface is:
+
+```julia
+CommonSolve.solve(prob::ProblemType,alg::SolverType; kwargs...)::SolutionType
+```
+
+where the keyword arguments are uniform across all choices of algorithms.
+
+By default, `solve` defaults to using `solve!` on the iterator form, i.e.:
+
+```julia
+solve(args...; kwargs...) = solve!(init(args...; kwargs...))
+```
+"""
 solve(args...; kwargs...) = solve!(init(args...; kwargs...))
+
+"""
+```julia
+CommonSolve.solve!(iter)
+```
+
+Solves an equation or other mathematical problem using the algorithm
+specified in the arguments. Generally, the interface is:
+
+```julia
+iter = CommonSolve.init(prob::ProblemType,alg::SolverType; kwargs...)::IterType
+CommonSolve.solve!(iter)::SolutionType
+```
+
+where the keyword arguments are uniform across all choices of algorithms.
+The `iter` type will be different for the different problem types.
+"""
 function solve! end
+
+"""
+```julia
+iter = CommonSolve.init(args...; kwargs...)
+```
+
+Solves an equation or other mathematical problem using the algorithm
+specified in the arguments. Generally, the interface is:
+
+```julia
+iter = CommonSolve.init(prob::ProblemType,alg::SolverType; kwargs...)::IterType
+CommonSolve.solve!(iter)::SolutionType
+```
+
+where the keyword arguments are uniform across all choices of algorithms.
+The `iter` type will be different for the different problem types.
+"""
 function init end
 
 end # module

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+pages = [`
	`2`	`+ "The Common Solve Interface" => "index.md",`
	`3`	`+]`