Reorganise documentation

EpiAware/README.md

@@ -5,90 +5,8 @@
 [![Test EpiAware](https://github.com/CDCgov/Rt-without-renewal/actions/workflows/test-EpiAware.yaml/badge.svg)](https://github.com/CDCgov/Rt-without-renewal/actions/workflows/test-EpiAware.yaml)
 [![codecov](https://codecov.io/gh/CDCgov/Rt-without-renewal/graph/badge.svg?token=IX4GIA8F0H)](https://codecov.io/gh/CDCgov/Rt-without-renewal)
 
-A `Julia` package for flexible and composable modeling and inference of the effective reproduction number (Rt) and other situational awareness signals in the presence of different latent generative processes and observation models.
+*Infectious disease situational awareness modelling toolkit for Julia.*
 
-## Installation instruction
+**Websites**: [Organization Website](https://cdcgov.github.io/Rt-without-renewal/dev/) | [Documentation](https://cdcgov.github.io/Rt-without-renewal/dev/)
 
-Eventually, `EpiAware` is likely to be added to the Julia registry. Until then, you can install it from the `/EpiAware` sub-directory of this repository by running the following command in the Julia REPL:
-
-```julia
-using Pkg; Pkg.add(url="https://github.com/CDCgov/Rt-without-renewal", subdir="EpiAware")
-```
-
-## Model Diagram
-
-- Solid lines indicate implemented features/analysis.
-- Dashed lines indicate planned features/analysis.
-
-## Current `EpiAware` model diagram
-```mermaid
-flowchart LR
-
-A["Underlying GI
-Bijector"]
-
-EpiModel["AbstractTuringEpiModel
-----------------------
-Choice of target
-for latent process:
-
-DirectInfections
-    ExpGrowthRate
-    Renewal"]
-
-InitModel["Priors for
-initial scale of incidence"]
-
-DataW[Data wrangling and QC]
-
-
-ObsData["Observational Data
----------------------
-Obs. cases y_t"]
-
-LatentProcPriors["Latent process priors"]
-
-LatentProc["AbstractTuringLatentModel
----------------------
-RandomWalk"]
-
-ObsModelPriors["Observation model priors
-choice of delayed obs. model"]
-
-ObsModel["AbstractObservationModel
----------------------
-DelayObservations"]
-
-E["Turing model constructor
----------------------
-generate_epiaware"]
-
-G[Posterior draws]
-H[Posterior checking]
-I[Post-processing]
-
-
-
-A --> EpiData
-EpiData --> EpiModel
-InitModel --> EpiModel
-EpiModel -->E
-ObsData-->E
-DataW-.->ObsData
-LatentProcPriors-->LatentProc
-LatentProc-->E
-ObsModelPriors-->ObsModel
-ObsModel-->E
-
-
-E-->|sample...NUTS...| G
-G-.->H
-H-.->I
-```
-
-## Pluto scripts
-
-We use [`Pluto.jl`](https://plutojl.org/) scripts as part of our documentation and testing. The scripts are located in `docs/src/examples` and can be run using the `Pluto.jl` package. We recommend using the version of `Pluto` that is pinned in the `Project.toml` file defining the documentation environment. An entry point to running or developing this documentation is the `docs/pluto-scripts.sh` bash shell script. Run this from the root directory of this repository.
-
-## Opinionated guide to using Julia for project development
-Some user and potential contributors may not be familiar with using Julia for, or part of, project development. In documentation we give our opinions on how to use Julia for project development focussing on Julia version control with the command line tool `juliaup`, typical patterns for using stacked environments and useful settings for development using the Julia extension of VS-Code as an interactive development environment (IDE) for Julia project. Please find the documentation [here](https://cdcgov.github.io/Rt-without-renewal/dev/man/getting-started-julia/).
+EpiAware Organization Stats: ![EpiAware Stars](https://img.shields.io/github/stars/EpiAware?style=social)

EpiAware/docs/make.jl

@@ -1,19 +1,29 @@
 using Documenter
 using EpiAware
+using EpiAware.EpiAwareBase
+using EpiAware.EpiAwareUtils
+using EpiAware.EpiInference
+using EpiAware.EpiInfModels
+using EpiAware.EpiLatentModels
+using EpiAware.EpiObsModels
 using Pluto: Configuration.CompilerOptions
 using PlutoStaticHTML
 
 include("changelog.jl")
 include("pages.jl")
 include("build.jl")
 
-build("examples")
+build("getting-started")
+build("getting-started/tutorials")
+build("showcase/replications/mishra-2020")
 
 makedocs(; sitename = "EpiAware.jl",
     authors = "Samuel Brand, Zachary Susswein, Sam Abbott, and contributors",
     clean = true, doctest = true, linkcheck = true,
     warnonly = [:docs_block, :missing_docs, :linkcheck, :autodocs_block],
-    modules = [EpiAware],
+    modules = [
+        EpiAware, EpiAware.EpiAwareBase, EpiAware.EpiAwareUtils, EpiAware.EpiInference,
+        EpiAware.EpiInfModels, EpiAware.EpiLatentModels, EpiAware.EpiObsModels],
     pages = pages,
     format = Documenter.HTML(
         prettyurls = get(ENV, "CI", nothing) == "true",

EpiAware/docs/pages.jl

@@ -1,18 +1,39 @@
 pages = [
     "EpiAware.jl: Real-time epidemic monitoring" => "index.md",
-    "Manual" => Any[
-        "Getting Started with using Julia in Projects" => "man/getting-started-julia.md",
-        "Examples" => [
-            "Getting started" => "examples/getting_started.md"
+    "Getting started" => Any[
+        "Installation" => "getting-started/installation.md",
+        "Quickstart" => "getting-started/quickstart.md",
+        "Tips and Tricks" => "getting-started/tips-and-tricks.md",
+        "Tutorials" => [
+            "Working with Julia" => "getting-started/tutorials/julia.md",
+            "Introduction to EpiAware" => "getting-started/tutorials/intro.md",
+            "Epidemic modelling" => "getting-started/tutorials/epidemic-modelling.md",
+            "Inference" => "getting-started/tutorials/inference.md",
+            "Latent models" => "getting-started/tutorials/latent-models.md",
+            "Observation models" => "getting-started/tutorials/observation-models.md"
         ]
     ],
-    "Reference" => Any[
-        "Public API" => "lib/public.md"
+    "Showcase" => [
+        "Replication" => [
+        "On the derivation of the renewal equation from an age-dependent branching process: an epidemic modelling perspective" => "showcase/replications/mishra-2020/index.md"
+    ]
+    ],
+    "What is EpiAware?" => ["overview.md"],
+    "Modules" => [
+        "EpiAware" => "lib/EpiAwareBase/index.md",
+        "EpiAwareUtils" => "lib/EpiAwareUtils/index.md",
+        "EpiInference" => "lib/EpiInference/index.md",
+        "EpiInfModels" => "lib/EpiInfModels/index.md",
+        "EpiLatentModels" => "lib/EpiLatentModels/index.md",
+        "EpiObsModels" => "lib/EpiObsModels/index.md",
+        "EpiAware" => [
+            "Public API" => "lib/public.md",
+            "Internal API" => "lib/internals.md"
+        ]
     ],
     "Developers" => [
-        "Contributing" => "man/contributing.md",
-        "Release checklist" => "checklist.md",
-        "Internals" => "lib/internals.md"
+        "Contributing" => "developer/contributing.md",
+        "Release checklist" => "developer/checklist.md"
     ],
     "release-notes.md"
 ]

EpiAware/docs/src/man/contributing.md → EpiAware/docs/src/developer/contributing.md

@@ -16,11 +16,11 @@ Feel free to nominate commits that should be backported by opening an issue. Req
 
 ### `release-*` branches
 
-  * Each new minor version `x.y.0` gets a branch called `release-x.y` (a [protected branch](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches)).
-  * New versions are usually tagged only from the `release-x.y` branches.
-  * For patch releases, changes get backported to the `release-x.y` branch via a single PR with the standard name "Backports for x.y.z" and label ["Type: Backport"](https://github.com/JuliaDocs/Documenter.jl/pulls?q=label%3A%22Type%3A+Backport%22). The PR message links to all the PRs that are providing commits to the backport. The PR gets merged as a merge commit (i.e. not squashed).
-  * The old `release-*` branches may be removed once they have outlived their usefulness.
-  * Patch version [milestones](https://github.com/CDCgov/Rt-without-renewal/milestones) are used to keep track of which PRs get backported etc.
+* Each new minor version `x.y.0` gets a branch called `release-x.y` (a [protected branch](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches)).
+* New versions are usually tagged only from the `release-x.y` branches.
+* For patch releases, changes get backported to the `release-x.y` branch via a single PR with the standard name "Backports for x.y.z" and label ["Type: Backport"](https://github.com/JuliaDocs/Documenter.jl/pulls?q=label%3A%22Type%3A+Backport%22). The PR message links to all the PRs that are providing commits to the backport. The PR gets merged as a merge commit (i.e. not squashed).
+* The old `release-*` branches may be removed once they have outlived their usefulness.
+* Patch version [milestones](https://github.com/CDCgov/Rt-without-renewal/milestones) are used to keep track of which PRs get backported etc.
 
 ## Style Guide
 

EpiAware/docs/src/getting-started/installation.md

@@ -0,0 +1,7 @@
+# Installation
+
+Eventually, `EpiAware` is likely to be added to the Julia registry. Until then, you can install it from the `/EpiAware` sub-directory of this repository by running the following command in the Julia REPL:
+
+```julia
+using Pkg; Pkg.add(url="https://github.com/CDCgov/Rt-without-renewal", subdir="EpiAware")
+```

EpiAware/docs/src/getting-started/quickstart.md

@@ -0,0 +1,3 @@
+# Quickstart
+
+Get up and running with EpiAware in just a few minutes using this quickstart guide.

EpiAware/docs/src/getting-started/tips-and-tricks.md

@@ -0,0 +1,9 @@
+# Tips and tricks
+
+```@index
+Pages = ["lib/getting-started/tips-and-tricks.md"]
+```
+
+## Pluto scripts
+
+We use [`Pluto.jl`](https://plutojl.org/) scripts as part of our documentation and testing. The scripts are located in `docs/src/examples` and can be run using the `Pluto.jl` package. We recommend using the version of `Pluto` that is pinned in the `Project.toml` file defining the documentation environment. An entry point to running or developing this documentation is the `docs/pluto-scripts.sh` bash shell script. Run this from the root directory of this repository.

EpiAware/docs/src/getting-started/tutorials/interfaces.md

@@ -0,0 +1,27 @@
+
+# Interfaces
+
+
+We support two primary workflows for using the package:
+
+- `EpiProblem`: A high-level interface for defining and fitting models to data. This is the recommended way to use the package.
+- `Turing` interface: A lower-level interface for defining and fitting models to data. This is the more flexible way to use the package and may also be more familiar to users of `Turing.jl`.
+
+See the getting started section for tutorials on each of these workflows.
+
+## EpiProblem
+
+Each module of the overall epidemiological model we are interested in is a `Turing` `Model` in its own right. In this section, we compose the individual models into the full epidemiological model using the `EpiProblem` struct.
+
+The constructor for an `EpiProblem` requires:
+
+- An `epi_model`.
+- A `latent_model`.
+- An `observation_model`.
+- A `tspan`.
+
+The `tspan` set the range of the time index for the models.
+
+## Turing interface
+
+The `Turing` interface is a lower-level interface for defining and fitting models to data. This is the more flexible way to use the package and may also be more familiar to users of `Turing.jl`.

EpiAware/docs/src/getting-started/tutorials/intro.md

@@ -0,0 +1,66 @@
+The diagram below shows the relationship between the modules in the package for a typical workflow.
+
+```mermaid
+flowchart LR
+
+A["Underlying GI
+Bijector"]
+
+EpiModel["AbstractTuringEpiModel
+----------------------
+Choice of target
+for latent process:
+
+DirectInfections
+    ExpGrowthRate
+    Renewal"]
+
+InitModel["Priors for
+initial scale of incidence"]
+
+DataW[Data wrangling and QC]
+
+
+ObsData["Observational Data
+---------------------
+Obs. cases y_t"]
+
+LatentProcPriors["Latent process priors"]
+
+LatentProc["AbstractTuringLatentModel
+---------------------
+RandomWalk"]
+
+ObsModelPriors["Observation model priors
+choice of delayed obs. model"]
+
+ObsModel["AbstractObservationModel
+---------------------
+DelayObservations"]
+
+E["Turing model constructor
+---------------------
+generate_epiaware"]
+
+G[Posterior draws]
+H[Posterior checking]
+I[Post-processing]
+
+
+
+A --> EpiData
+EpiData --> EpiModel
+InitModel --> EpiModel
+EpiModel -->E
+ObsData-->E
+DataW-.->ObsData
+LatentProcPriors-->LatentProc
+LatentProc-->E
+ObsModelPriors-->ObsModel
+ObsModel-->E
+
+
+E-->|sample...NUTS...| G
+G-->H
+H-->I
+```