Merge pull request #67 from neonWhiteout/StyleAdherence

Style adherence

docs/.gitignore

@@ -0,0 +1,2 @@
+build/
+src/generated/

docs/make.jl

@@ -0,0 +1,59 @@
+using Documenter
+using Literate
+
+const literate_dir = joinpath(@__DIR__, "literate")
+const generated_dir = joinpath(@__DIR__, "src", "generated")
+
+@info "Loading StockFlow.jl"
+using StockFlow
+
+const no_literate = "--no-literate" in ARGS
+if !no_literate
+  @info "Building Literate.jl docs"
+
+  # XXX: Work around old LaTeX distribution in GitHub CI.
+  if haskey(ENV, "GITHUB_ACTIONS")
+    import TikzPictures
+    TikzPictures.standaloneWorkaround(true)
+  end
+
+  # Set Literate.jl config if not being compiled on recognized service.
+  config = Dict{String,String}()
+  if !(haskey(ENV, "GITHUB_ACTIONS") || haskey(ENV, "GITLAB_CI"))
+    config["nbviewer_root_url"] = "https://nbviewer.jupyter.org/github/AlgebraicJulia/StockFlow.jl/blob/gh-pages/dev"
+    config["repo_root_url"] = "https://github.com/AlgebraicJulia/StockFlow.jl/blob/main/docs"
+  end
+
+  for (root, dirs, files) in walkdir(literate_dir)
+    out_dir = joinpath(generated_dir, relpath(root, literate_dir))
+    for file in files
+      if last(splitext(file)) == ".jl"
+        Literate.markdown(joinpath(root, file), out_dir;
+                          config=config, documenter=true, credit=false)
+        Literate.notebook(joinpath(root, file), out_dir;
+                          execute=true, documenter=true, credit=false)
+      end
+    end
+  end
+end
+
+@info "Building Documenter.jl docs"
+makedocs(
+  modules     = [StockFlow],
+  format      = Documenter.HTML(
+                                assets = ["assets/analytics.js"],
+                               ),
+  sitename    = "StockFlow.jl",
+  doctest     = false,
+  checkdocs   = :none,
+  pages       = Any[
+    "StockFlow.jl" => "index.md",
+  ]
+)
+
+@info "Deploying docs"
+deploydocs(
+  target = "build",
+  repo   = "github.com/AlgebraicJulia/StockFlow.jl.git",
+  branch = "gh-pages"
+)

docs/src/index.md

@@ -0,0 +1,10 @@
+# [StockFlow](@id StockFlow)
+
+```@autodocs
+Modules = [
+    StockFlow,
+    StockFlow.Syntax,
+    StockFlow.PremadeModels
+]
+Private = false
+```

src/CausalLoop.jl

@@ -2,7 +2,6 @@ export TheoryCausalLoop, AbstractCausalLoop, CausalLoopUntyped, CausalLoop, nn,
 sedge, tedge, convertToCausalLoop, nnames
 
 
-
 @present TheoryCausalLoop(FreeSchema) begin
   E::Ob
   N::Ob
@@ -26,6 +25,10 @@ add_nodes!(c::AbstractCausalLoop,n;kw...) = add_parts!(c,:N,n;kw...)
 add_edge!(c::AbstractCausalLoop,s,t;kw...) = add_part!(c,:E,s=s,t=t;kw...) 
 add_edges!(c::AbstractCausalLoop,n,s,t;kw...) = add_parts!(c,:E,n,s=s,t=t;kw...)
 
+"""
+    CausalLoop(ns,es)
+Create causal loop diagram from collection of nodes and collection of edges.
+"""
 CausalLoop(ns,es) = begin
     c = CausalLoop()
     ns = vectorify(ns)
@@ -42,15 +45,22 @@ CausalLoop(ns,es) = begin
 end
 
 # return the count of each components
+""" return count of nodes of CLD """
 nn(c::AbstractCausalLoop) = nparts(c,:N) #nodes
+""" return count of edges of CLD """
 ne(c::AbstractCausalLoop) = nparts(c,:E) #edges
 
+""" return node's name with index n """
 nname(c::AbstractCausalLoop,n) = subpart(c,n,:nname) # return the node's name with index of s
+""" return edge's name with target number t """
 sedge(c::AbstractCausalLoop,e) = subpart(c,e,:s)
+""" return edge's name with edge number e """
 tedge(c::AbstractCausalLoop,e) = subpart(c,e,:t)
 
+""" return node names of CLD """
 nnames(c::AbstractCausalLoop) = [nname(c, n) for n in 1:nn(c)]
 
+
 function convertToCausalLoop(p::AbstractStockAndFlowStructure)
 
     sns=snames(p)
@@ -73,6 +83,11 @@ function convertToCausalLoop(p::AbstractStockAndFlowStructure)
     return CausalLoop(ns,es)
 end
 
+"""
+Convert StockFlow to CLD.
+Nodes: stocks, flows, sum variables, parameters, nonflow dynamic variables
+Edges: morphisms in stock flow
+"""
 function convertToCausalLoop(p::AbstractStockAndFlowStructureF)
 
     sns=snames(p)

src/PremadeModels.jl

@@ -4,18 +4,30 @@ using ..StockFlow.Syntax
 
 export seir, sis, sir, svi
 
+"""
+Return a new SEIR model
+"""
 function seir()
     return deepcopy(seir_model)
 end
 
+"""
+Return a new SIS model
+"""
 function sis()
     return deepcopy(sis_model)
 end
 
+"""
+Return a new SIR model
+"""
 function sir()
     return deepcopy(sir_model)
 end
 
+"""
+Return a new SVI model
+"""
 function svi()
     return deepcopy(svi_model)
 end