Merge pull request #146 from MineralsCloud:docs

Update docs

docs/make.jl

@@ -1,7 +1,13 @@
 using SimpleWorkflows
 using Documenter
 
-DocMeta.setdocmeta!(SimpleWorkflows, :DocTestSetup, :(using SimpleWorkflows); recursive=true)
+DocMeta.setdocmeta!(
+    SimpleWorkflows,
+    :DocTestSetup,
+    :(using SimpleWorkflows,
+        SimpleWorkflows.Thunks, SimpleWorkflows.Jobs, SimpleWorkflows.Workflows);
+    recursive=true,
+)
 
 makedocs(;
     modules=[SimpleWorkflows],

docs/src/public.md

@@ -8,37 +8,62 @@ CurrentModule = SimpleWorkflows
 Pages = ["public.md"]
 ```
 
-## Jobs
+```@meta
+CurrentModule = SimpleWorkflows.Thunks
+```
+
+## `Thunks` module
+
+```@docs
+Thunk
+reify!
+getresult(::Thunk)
+```
+
+```@meta
+CurrentModule = SimpleWorkflows.Jobs
+```
+
+## `Jobs` module
 
 ```@docs
 Job
-@job
-getresult
-getstatus(x::Job)
+getresult(::Job)
+getstatus(::Job)
 ispending
 isrunning
 isexited
 issucceeded
 isfailed
 isinterrupted
+pendingjobs
+runningjobs
+exitedjobs
+succeededjobs
+failedjobs
+interruptedjobs
 createdtime
 starttime
 stoptime
 elapsed
 description
-run!(job::Job; n=1, δt=1)
+run!(::Job)
 interrupt!
 queue
 query
 ntimes
 ```
 
-## Workflows
+```@meta
+CurrentModule = SimpleWorkflows.Workflows
+```
+
+## `Workflows` module
 
 ```@docs
 Workflow
-run!(wf::Workflow; n=5, δt=1, Δt=1, filename="saved.jld2")
-getstatus(wf::Workflow)
+run!(::Workflow)
+getstatus(::Workflow)
 chain
 →
 ←
@@ -48,4 +73,10 @@ thread
 fork
 converge
 spindle
+pendingjobs(::Workflow)
+runningjobs(::Workflow)
+exitedjobs(::Workflow)
+succeededjobs(::Workflow)
+failedjobs(::Workflow)
+interruptedjobs(::Workflow)
 ```

src/Jobs/Jobs.jl

@@ -17,19 +17,20 @@ end
 
 # Reference: https://github.com/cihga39871/JobSchedulers.jl/blob/aca52de/src/jobs.jl#L35-L69
 """
-    Job(def; desc="", user="")
+    Job(thunk::Thunk; desc="", user="")
 
 Create a simple job.
 
 # Arguments
-- `def`: A closure that encloses the job definition.
-- `desc::String=""`: Describe briefly what this job does.
-- `user::String=""`: Indicate who executes this job.
+- `thunk`: a `Thunk` that encloses the job definition.
+- `desc::String=""`: describe briefly what this job does.
+- `user::String=""`: indicate who executes this job.
 
 # Examples
-```@repl
-a = Job(() -> sleep(5); user="me", desc="Sleep for 5 seconds")
-b = Job(() -> run(`pwd` & `ls`); user="me", desc="Run some commands")
+```jldoctest
+julia> a = Job(Thunk(sleep)(5); user="me", desc="Sleep for 5 seconds");
+
+julia> b = Job(Thunk(run, `pwd` & `ls`); user="me", desc="Run some commands");
 ```
 """
 mutable struct Job
@@ -47,7 +48,7 @@ mutable struct Job
     parents::Vector{Job}
     "These jobs runs after the current job."
     children::Vector{Job}
-    Job(thunk; desc = "", user = "") =
+    Job(thunk::Thunk; desc = "", user = "") =
         new(uuid1(), thunk, desc, user, now(), DateTime(0), DateTime(0), PENDING, 0, [], [])
 end
 """

src/Jobs/status.jl

@@ -38,14 +38,44 @@ isfailed(job::Job) = getstatus(job) === FAILED
 "Test if the `Job` was interrupted during running."
 isinterrupted(job::Job) = getstatus(job) === INTERRUPTED
 
+"""
+    pendingjobs(jobs)
+
+Filter only the pending jobs in a sequence of `Job`s.
+"""
 pendingjobs(jobs) = filter(ispending, jobs)
 
+"""
+    runningjobs(jobs)
+
+Filter only the running jobs in a sequence of `Job`s.
+"""
 runningjobs(jobs) = filter(isrunning, jobs)
 
+"""
+    exitedjobs(jobs)
+
+Filter only the exited jobs in a sequence of `Job`s.
+"""
 exitedjobs(jobs) = filter(isexited, jobs)
 
+"""
+    succeededjobs(jobs)
+
+Filter only the succeeded jobs in a sequence of `Job`s.
+"""
 succeededjobs(jobs) = filter(issucceeded, jobs)
 
+"""
+    failedjobs(jobs)
+
+Filter only the failed jobs in a sequence of `Job`s.
+"""
 failedjobs(jobs) = filter(isfailed, jobs)
 
+"""
+    interruptedjobs(jobs)
+
+Filter only the interrupted jobs in a sequence of `Job`s.
+"""
 interruptedjobs(jobs) = filter(isinterrupted, jobs)

src/Thunks.jl

@@ -2,6 +2,45 @@ module Thunks
 
 export Thunk, reify!, getresult
 
+# Idea from https://github.com/tbenst/Thunks.jl/blob/ff2a553/src/core.jl#L11-L20
+"""
+    Thunk(::Function, args::Tuple, kwargs::NamedTuple)
+    Thunk(::Function, args...; kwargs...)
+    Thunk(::Function)
+
+Hold a `Function` and its arguments for lazy evaluation. Use `reify!` to evaluate.
+
+# Examples
+```jldoctest
+julia> a = Thunk(x -> 3x, 4);
+
+julia> reify!(a)
+Some(12)
+
+julia> b = Thunk(+, 4, 5);
+
+julia> reify!(b)
+Some(9)
+
+julia> c = Thunk(sleep)(1);
+
+julia> getresult(c)  # `c` has not been evaluated
+
+julia> reify!(c)  # `c` has been evaluated
+Some(nothing)
+
+julia> f(args...; kwargs...) = collect(kwargs);
+
+julia> d = Thunk(f)(1, 2, 3; x=1.0, y=4, z="5");
+
+julia> reify!(d)
+Some(Pair{Symbol, Any}[:x => 1.0, :y => 4, :z => "5"])
+
+julia> e = Thunk(sin, "1");  # Catch errors
+
+julia> reify!(e);
+```
+"""
 mutable struct Thunk
     f
     args::Tuple
@@ -15,6 +54,18 @@ end
 Thunk(f, args...; kwargs...) = Thunk(f, args, NamedTuple(kwargs))
 Thunk(f) = (args...; kwargs...) -> Thunk(f, args, NamedTuple(kwargs))
 
+# See https://github.com/tbenst/Thunks.jl/blob/ff2a553/src/core.jl#L113-L123
+"""
+    reify!(thunk::Thunk)
+
+Reify a `Thunk` into a value.
+
+Compute the value of the expression.
+Walk through the `Thunk`'s arguments and keywords, recursively evaluating each one,
+and then evaluating the `Thunk`'s function with the evaluated arguments.
+
+See also [`Thunk`](@ref).
+"""
 function reify!(thunk::Thunk)
     if thunk.evaluated
         return getresult(thunk)
@@ -30,6 +81,11 @@ function reify!(thunk::Thunk)
     end
 end
 
+"""
+    getresult(thunk::Thunk)
+
+Get the result of a `Thunk`. If `thunk` has not been evaluated, return `nothing`, else return a `Some`-wrapped result.
+"""
 getresult(thunk::Thunk) = thunk.evaluated ? thunk.result : nothing
 
 function Base.show(io::IO, thunk::Thunk)

src/Workflows/operations.jl

@@ -1,7 +1,7 @@
 export chain, thread, fork, converge, spindle, →, ←, ⇶, ⬱, ⇉, ⭃
 
 """
-chain(x::Job, y::Job, z::Job...)
+    chain(x::Job, y::Job, z::Job...)
 
 Chain multiple `Job`s one after another.
 """
@@ -16,20 +16,20 @@ function chain(x::Job, y::Job)
 end
 chain(x::Job, y::Job, z::Job...) = foldr(chain, (x, y, z...))
 """
-→(x, y)
+    →(x, y)
 
 Chain two `Job`s.
 """
 →(x::Job, y::Job) = chain(x, y)
 """
-←(y, x)
+    ←(y, x)
 
 Chain two `Job`s reversely.
 """
 ←(y::Job, x::Job) = x → y
 
 """
-thread(xs::AbstractVector{Job}, ys::AbstractVector{Job}, zs::AbstractVector{Job}...)
+    thread(xs::AbstractVector{Job}, ys::AbstractVector{Job}, zs::AbstractVector{Job}...)
 
 Chain multiple vectors of `Job`s, each `Job` in `xs` has a corresponding `Job` in `ys`.`
 """
@@ -45,21 +45,21 @@ end
 thread(xs::AbstractVector{Job}, ys::AbstractVector{Job}, zs::AbstractVector{Job}...) =
     foldr(thread, (xs, ys, zs...))
 """
-⇶(xs, ys)
+    ⇶(xs, ys)
 
 Chain two vectors of `Job`s.
 """
 ⇶(xs::AbstractVector{Job}, ys::AbstractVector{Job}) = thread(xs, ys)
 """
-⬱(ys, xs)
+    ⬱(ys, xs)
 
 Chain two vectors of `Job`s reversely.
 """
 ⬱(ys::AbstractVector{Job}, xs::AbstractVector{Job}) = xs ⇶ ys
 
 """
-fork(x::Job, ys::AbstractVector{Job})
-⇉(x, ys)
+    fork(x::Job, ys::AbstractVector{Job})
+    ⇉(x, ys)
 
 Attach a group of parallel `Job`s (`ys`) to a single `Job` (`x`).
 """
@@ -72,8 +72,8 @@ end
 const ⇉ = fork
 
 """
-converge(xs::AbstractVector{Job}, y::Job)
-⭃(xs, y)
+    converge(xs::AbstractVector{Job}, y::Job)
+    ⭃(xs, y)
 
 Finish a group a parallel `Job`s (`xs`) by a single `Job` (`y`).
 """
@@ -86,7 +86,7 @@ end
 const ⭃ = converge
 
 """
-spindle(x::Job, ys::AbstractVector{Job}, z::Job)
+    spindle(x::Job, ys::AbstractVector{Job}, z::Job)
 
 Start from a `Job` (`x`), followed by a series of `Job`s (`ys`), finished by a single `Job` (`z`).
 """

src/Workflows/run!.jl

@@ -8,12 +8,11 @@ import ..SimpleWorkflows: run!
 export run!
 
 """
-    run!(wf::Workflow; n=5, δt=1, Δt=1, filename="saved.jld2")
+    run!(wf::Workflow; n=5, δt=1, Δt=1)
 
 Run a `Workflow` with maximum `n` attempts, with each attempt separated by `Δt` seconds.
 
-Cool down for `δt` seconds after each `Job` in the `Workflow`. Save the tracking information
-to a file named `saved.jld2`.
+Cool down for `δt` seconds after each `Job` in the `Workflow`.
 """
 function run!(wf::Union{Workflow,SavedWorkflow}; n = 5, δt = 1, Δt = 1)
     @assert isinteger(n) && n >= 1

src/Workflows/status.jl

@@ -1,11 +1,34 @@
-import ..Jobs: getstatus, pendingjobs, runningjobs, exitedjobs, failedjobs, interruptedjobs
+import ..Jobs:
+    getstatus,
+    pendingjobs,
+    runningjobs,
+    exitedjobs,
+    succeededjobs,
+    failedjobs,
+    interruptedjobs
 
-export getstatus, pendingjobs, runningjobs, exitedjobs, failedjobs, interruptedjobs
+export getstatus,
+    pendingjobs, runningjobs, exitedjobs, succeededjobs, failedjobs, interruptedjobs
 
-for method in
-    (:getstatus, :pendingjobs, :runningjobs, :exitedjobs, :failedjobs, :interruptedjobs)
+"""
+    getstatus(wf::Workflow)
+
+Get the current status of `Job`s in a `Workflow`.
+"""
+getstatus(wf::Workflow) = getstatus(wf.jobs)
+getstatus(wf::SavedWorkflow) = getstatus(wf.wf)
+
+# See https://docs.julialang.org/en/v1/manual/documentation/#Advanced-Usage
+for func in
+    (:pendingjobs, :runningjobs, :exitedjobs, :succeededjobs, :failedjobs, :interruptedjobs)
+    name = string(func)
     @eval begin
-        $method(wf::Workflow) = $method(wf.jobs)
-        $method(wf::SavedWorkflow) = $method(wf.wf)
+        """
+            $($name)(wf::Workflow)
+
+        Filter only the pending jobs in a `Workflow`.
+        """
+        $func(wf::Workflow) = $func(wf.jobs)
+        $func(wf::SavedWorkflow) = $func(wf.wf)
     end
 end