From bc2ebd24fc1db73736cf7fb13f5155f114215a7a Mon Sep 17 00:00:00 2001
From: Misha Mikhasenko <mikhail.mikhasenko@cern.ch>
Date: Thu, 22 Aug 2024 00:49:10 +0200
Subject: [PATCH] Literate-in-docs (#46)

* add tutorial to documentation
* add literate to docs
* theme
* remove demo link
---
 .cspell/julia.txt                    |  3 ++-
 README.md                            |  2 --
 docs/Project.toml                    |  7 +++----
 docs/make.jl                         | 25 ++++++++++++++++++++++++-
 docs/src/{demo.jl => 10-tutorial.jl} | 17 ++++++++++++++---
 5 files changed, 43 insertions(+), 11 deletions(-)
 rename docs/src/{demo.jl => 10-tutorial.jl} (94%)

diff --git a/.cspell/julia.txt b/.cspell/julia.txt
index eb1e190..ec3c8f1 100644
--- a/.cspell/julia.txt
+++ b/.cspell/julia.txt
@@ -1,3 +1,4 @@
+autodocs
 btime
 circleorigin
 coeffs
@@ -28,6 +29,7 @@ mssq
 nonpole
 permutedims
 polardalitz
+postprocess
 println
 rborder
 reim
@@ -49,4 +51,3 @@ warntype
 σjofk
 σkmax
 σkmin
-autodocs
diff --git a/README.md b/README.md
index 0a4f7e4..b697de2 100644
--- a/README.md
+++ b/README.md
@@ -27,8 +27,6 @@ The code mostly inherits notations of the paper:
 - `ζ_kj_for_0` is the Wigner angle of the 0-particle, an angle of `vec pⱼ+pⱼ` with respect the the chain `j`.
 - `ζ_ij_for_k` is the Wigner angle for the particle `k` (the angle in the rest frame of particle `k`) that is mismatched for the chain `i` with respect to the chain `j`.
 
-See [example](docs/src/demo.jl) for a demonstration case.
-
 ## Installation
 
 ```julia
diff --git a/docs/Project.toml b/docs/Project.toml
index 5567c65..d446ec5 100644
--- a/docs/Project.toml
+++ b/docs/Project.toml
@@ -1,10 +1,9 @@
-# Don't forget to run
-#
-#     pkg> dev ..
-#
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
 LiveServer = "16fef848-5104-11e9-1b77-fb7a48bbb589"
+Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
+QuadGK = "1fd47b50-473d-5c70-9696-f719f8f3bcdc"
 ThreeBodyDecays = "e6563dab-9ca1-5843-bde3-2ccf38d63843"
 
 [compat]
diff --git a/docs/make.jl b/docs/make.jl
index b67edec..6cc0e2f 100644
--- a/docs/make.jl
+++ b/docs/make.jl
@@ -1,5 +1,6 @@
 using ThreeBodyDecays
 using Documenter
+using Literate
 
 DocMeta.setdocmeta!(
     ThreeBodyDecays,
@@ -10,6 +11,28 @@ DocMeta.setdocmeta!(
 
 const page_rename = Dict("developer.md" => "Developer docs") # Without the numbers
 
+function fix_literate_output(content)
+    content = replace(content, "EditURL = \"@__REPO_ROOT_URL__/\"" => "")
+    return content
+end
+
+docs_src_dir = joinpath(@__DIR__, "src")
+#
+files = readdir(docs_src_dir)
+filter!(file -> splitext(file)[2] == ".jl", files)
+map(files) do file
+    name = splitext(file)[1]
+    tutorial_src = joinpath(@__DIR__, "src", "$(name).jl")
+    Literate.markdown(
+        tutorial_src,
+        docs_src_dir;
+        name,
+        documenter = true,
+        credit = true,
+        postprocess = fix_literate_output,
+    )
+end
+
 makedocs(;
     modules = [ThreeBodyDecays],
     authors = "Misha Mikhasenko <mikhail.mikhasenko@cern.ch> and contributors",
@@ -22,7 +45,7 @@ makedocs(;
     pages = [
         "index.md"
         [
-            file for file in readdir(joinpath(@__DIR__, "src")) if
+            file for file in readdir(docs_src_dir) if
             file != "index.md" && splitext(file)[2] == ".md"
         ]
     ],
diff --git a/docs/src/demo.jl b/docs/src/10-tutorial.jl
similarity index 94%
rename from docs/src/demo.jl
rename to docs/src/10-tutorial.jl
index b1e38a8..ba41cc0 100644
--- a/docs/src/demo.jl
+++ b/docs/src/10-tutorial.jl
@@ -12,7 +12,18 @@
 using ThreeBodyDecays # import the module
 using Plots
 using QuadGK
-theme(:wong2)
+#
+theme(
+    :wong,
+    frame = :box,
+    lab = "",
+    minorticks = true,
+    guidefontvalign = :top,
+    guidefonthalign = :right,
+    xlim = (:auto, :auto),
+    ylim = (0, :auto),
+    grid = false,
+)
 
 # decay Λb ⟶ Jψ p K
 constants = Dict("mJψ" => 3.09, "mp" => 0.938, "mK" => 0.49367, "mLb" => 5.62) # masses of the particles
@@ -74,7 +85,7 @@ end
     Ps = Conserving,
     tbs = tbs,
 )
-Λs = (Λ1520, Λ1690, Λ1810)
+Λs = (Λ1520, Λ1690, Λ1810);
 
 # chains-3, i.e. (1+2): Pentaquarks with the lowest ls, LS
 Pc4312 = DecayChainLS(
@@ -98,7 +109,7 @@ Pc4457 = DecayChainLS(
     Ps = Conserving,
     tbs = tbs,
 )
-Pcs = (Pc4312, Pc4440, Pc4457)
+Pcs = (Pc4312, Pc4440, Pc4457);
 
 # ## Unpolarized intensity