Add literate docs

.gitignore

@@ -12,5 +12,6 @@ docs/**/*.svg
 *.csv
 *.txt
 /docs/src/index.md
+/docs/src/examples/*.md
 .vscode/
 .benchmarkci/

docs/Project.toml

@@ -1,11 +1,13 @@
 [deps]
+DensityInterface = "b429d917-457f-4dbc-8f4c-0cc954292b1d"
 Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 DocumenterCitations = "daee34ce-89f3-4625-b898-19384cb65244"
 HiddenMarkovModels = "84ca31d5-effc-45e0-bfda-5a68cd981f47"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
 Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
+Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 SimpleUnPack = "ce78b400-467f-4804-87d8-8f486da07d0a"
 Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
 StatsAPI = "82ae8749-77ed-4fe6-ae5f-f523153014b0"

docs/make.jl

@@ -23,15 +23,42 @@ open(joinpath(joinpath(@__DIR__, "src"), "index.md"), "w") do io
     end
 end
 
+examples_jl_path = joinpath(dirname(@__DIR__), "examples")
+examples_md_path = joinpath(@__DIR__, "src", "examples")
+
+for file in readdir(examples_md_path)
+    if endswith(file, ".md")
+        rm(joinpath(examples_md_path, file))
+    end
+end
+
+for file in readdir(examples_jl_path)
+    Literate.markdown(joinpath(examples_jl_path, file), examples_md_path)
+end
+
+function literate_title(path)
+    l = first(readlines(path))
+    return l[3:end]
+end
+
 pages = [
-    "Home" => "index.md",
     "Essentials" => [
+        "Home" => "index.md",
         "Background" => "background.md",
-        "API reference" => "api.md",
         "Alternatives" => "alternatives.md",
     ],
-    "Tutorials" => ["Debugging" => "debugging.md"],
-    "Advanced" => ["Formulas" => "formulas.md", "Roadmap" => "roadmap.md"],
+    "Tutorials" => [
+        "Basics" => joinpath("examples", "basics.md"),
+        "Distributions" => joinpath("examples", "distributions.md"),
+        "Controlled" => joinpath("examples", "controlled.md"),
+        "Periodic" => joinpath("examples", "periodic.md"),
+    ],
+    "API reference" => "api.md",
+    "Advanced" => [
+        "Debugging" => "debugging.md",
+        "Formulas" => "formulas.md",
+        "Roadmap" => "roadmap.md",
+    ],
 ]
 
 fmt = Documenter.HTML(;

examples/hmm.jl → examples/basics.jl

@@ -1,12 +1,14 @@
-# # Built-in HMM
+# # Basics
 
 # ## Setup
 
 # Imports
 
 using Distributions
 using HiddenMarkovModels
+#md using Plots
 using Random
+using Test  #src
 
 # Random seed
 
@@ -18,7 +20,7 @@ Random.seed!(rng, 63)
 N = 2
 init = rand_prob_vec(N)
 trans = rand_trans_mat(N)
-dists = [Normal(i, 0.5) for i in 1:N]
+dists = [Normal(i, 1) for i in 1:N]
 hmm = HMM(init, trans, dists)
 
 # ## Simulation
@@ -44,20 +46,26 @@ forward_backward(hmm, obs_seq)
 
 # ## Learning from several sequences
 
-K = 3
-obs_seqs = [rand(rng, hmm, k * T).obs_seq for k in 1:K]
+nb_seqs = 3
+obs_seqs = [rand(rng, hmm, k * T).obs_seq for k in 1:nb_seqs]
 
 # Baum-Welch needs an initial guess
 
 init_guess = ones(N) / N
 trans_guess = ones(N, N) / N
-dists_guess = [Normal(i, 1) for i in 1:N]
+dists_guess = [Normal(i + randn() / 10, 1) for i in 1:N]
 hmm_guess = HMM(init_guess, trans_guess, dists_guess)
 
 #-
 
-hmm_est, logL_evolution = baum_welch(hmm_guess, obs_seqs, length(obs_seqs))
+hmm_est, logL_evolution = baum_welch(hmm_guess, obs_seqs, nb_seqs)
+
+#md plot(logL_evolution)
+
+#-
 
 first(logL_evolution), last(logL_evolution)
 
+#-
+
 cat(hmm_est.trans, hmm.trans; dims=3)

examples/controlled.jl

@@ -1,6 +1 @@
-struct ControlledHMM{R,C}
-    init::Vector{R}
-    trans::Matrix{R}
-    means::Vector{R}
-    control_seq::Vector{C}
-end
+# # Controlled HMM

examples/distributions.jl

@@ -0,0 +1 @@
+# # Distributions