Add a getting started tutorial (#109)

* update

* added doc deps

* started `getting started` notebook

* Update getting_started.jl

* Getting started example

* Add generated Pluto notebooks to gitignore

* remove old version of example

* add Pluto and PlutoStaticHTML as deps

* Adapt make and build files to generate Pluto notebooks statically and then render into docs

* include build step for rendering Pluto notebooks

* remove old version of the getting started example

* Update EpiAware/docs/src/examples/getting_started.jl

---------

Co-authored-by: Sam Abbott <[email protected]>

.gitignore

@@ -381,3 +381,6 @@ docs/site/
 /Manifest.toml
 .DS_Store
 .vscode/settings.json
+
+#Ignore generated Pluto notebooks
+EpiAware/docs/src/examples/*.md

EpiAware/docs/Project.toml

@@ -1,4 +1,13 @@
 [deps]
 Changelog = "5217a498-cd5d-4ec6-b8c2-9b85a09b6e3e"
+DataFramesMeta = "1313f7d8-7da2-5740-9ea0-a2ca25f37964"
+Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+DynamicPPL = "366bfd00-2699-11ea-058f-f148b4cae6d8"
 EpiAware = "b2eeebe4-5992-4301-9193-7ebc9f62c855"
+LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
+Pluto = "c3e4b0f8-55cb-11ea-2926-15256bba5781"
+PlutoStaticHTML = "359b1769-a58e-495b-9770-312e911026ad"
+Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
+StatsPlots = "f3b207a7-027a-5e70-b257-86293d7955fd"
+Turing = "fce5fe82-541a-59a6-adf8-730c64b5f9a0"

EpiAware/docs/build.jl

@@ -0,0 +1,24 @@
+
+"""Run all Pluto notebooks (".jl" files) in `tutorials_dir` and write outputs to HTML files."""
+function build(target_subdir; _module = EpiAware)
+    target_dir = joinpath(pkgdir(_module), "docs", "src", target_subdir)
+
+    @info "Building notebooks in $target_subdir"
+    # Evaluate notebooks in the same process to avoid having to recompile from scratch each time.
+    # This is similar to how Documenter and Franklin evaluate code.
+    # Note that things like method overrides and other global changes may leak between notebooks!
+    use_distributed = false
+    output_format = documenter_output
+    bopts = BuildOptions(target_dir; use_distributed, output_format)
+    build_notebooks(bopts)
+    return nothing
+end
+
+"Return Markdown file links which can be passed to Documenter.jl."
+function markdown_files(notebook_titles, target_subdir)
+    md_files = map(notebook_titles) do title
+        file = lowercase(replace(title, " " => '_'))
+        return joinpath(target_subdir, "$file.md")
+    end
+    return md_files
+end

EpiAware/docs/make.jl

@@ -1,8 +1,13 @@
 using Documenter
 using EpiAware
+using Pluto: Configuration.CompilerOptions
+using PlutoStaticHTML
 
 include("changelog.jl")
 include("pages.jl")
+include("build.jl")
+
+build("examples")
 
 makedocs(; sitename = "EpiAware.jl",
     authors = "Samuel Brand, Zachary Susswein, Sam Abbott, and contributors",
@@ -11,7 +16,10 @@ makedocs(; sitename = "EpiAware.jl",
     modules = [EpiAware],
     pages = pages,
     format = Documenter.HTML(
-        prettyurls = get(ENV, "CI", nothing) == "true"
+        prettyurls = get(ENV, "CI", nothing) == "true",
+        mathengine = Documenter.MathJax3(),
+        size_threshold = 600 * 2^10,
+        size_threshold_warn = 200 * 2^10
     )
 )
 

EpiAware/docs/pages.jl

@@ -3,7 +3,7 @@ pages = [
     "Manual" => Any[
         "Guide" => "man/guide.md",
         "Examples" => [
-            "Getting started" => "man/getting-started.md"
+            "Getting started" => "examples/getting_started.md"
         ]
     ],
     "Reference" => Any[