From 3468a9c5eda165445844812203c91a7060211c98 Mon Sep 17 00:00:00 2001 From: Samuel Brand Date: Tue, 23 Jul 2024 17:34:10 +0100 Subject: [PATCH] moving specific Pluto instructions into faq and env details into contributing --- EpiAware/docs/src/developer/contributing.md | 22 +++++++++++++++++++ EpiAware/docs/src/getting-started/faq.md | 3 +++ .../replications/mishra-2020/index.jl | 10 --------- 3 files changed, 25 insertions(+), 10 deletions(-) diff --git a/EpiAware/docs/src/developer/contributing.md b/EpiAware/docs/src/developer/contributing.md index 342bd419b..f61de58fb 100644 --- a/EpiAware/docs/src/developer/contributing.md +++ b/EpiAware/docs/src/developer/contributing.md @@ -39,3 +39,25 @@ As is conventional for Julia packages, unit tests are located at `test/*.jl` wit Tests that build example package docs from source and inspect the results (end to end tests) are located in `/test/examples`. The main entry points are `test/examples/make.jl` for building and `test/examples/test.jl` for doing some basic checks on the generated outputs. + +### Pluto usage in end to end tests and showcases +Some of the end to end tests and showcases use `Pluto.jl` scripts. + +We recommend using the version of `Pluto` that is pinned in the `Project.toml` file defining the documentation environment located at `EpiAware/docs`, as well as using this as the environment for running the `Pluto.jl` scripts. + +So as to test the ability of the tests/showcases to run using a development branch of `EpiAware` we recommend checking-out the branch version of `EpiAware` directly from its source code using `Pkg.develop`. The reason for this is that when committing a change to `EpiAware` we want the website to be built with the proposed branch of `EpiAware` as part of our checking before merging. + +An example of doing this would be adding this code block to a `Pluto.jl` script: + +```julia + using Pkg + sp = splitpath(@__DIR__) + docs_dir = sp |> sp -> sp[1:(findfirst(sp .== "docs"))] |> joinpath + pkg_dir = sp |> sp -> sp[1:(findfirst(sp .== "EpiAware"))] |> joinpath + + Pkg.activate(docs_dir) + Pkg.develop(; path = pkg_dir) + Pkg.instantiate() +``` + +This block searchs up the directory path from the location of the `Pluto.jl` script to find the `docs` directory and the `EpiAware` directory, and then activates the environment in the `docs` directory and checks out the `EpiAware` package from the `EpiAware` directory. diff --git a/EpiAware/docs/src/getting-started/faq.md b/EpiAware/docs/src/getting-started/faq.md index 85e3875f3..60ac12457 100644 --- a/EpiAware/docs/src/getting-started/faq.md +++ b/EpiAware/docs/src/getting-started/faq.md @@ -10,8 +10,11 @@ Pages = ["lib/getting-started/faq.md"] 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. +Note that `Pluto.jl` notebooks operate on single lines of code or code blocks encapsulated by `let ... end` and `begin ... end`. The reason is that `Pluto` notebooks are reactive, and re-run downstream code after changes with downstreaming determined by a tree of dependent code blocks. The difference between `let ... end` blocks and `begin ... end` blocks are that the `let ... end` type of code block only adds the final output/return value of the block to scope, like an anonymous function, whereas `begin ... end` executes each line and adds defined variables to scope. + ## Manipulating `EpiAware` model specifications ### Modular model construction diff --git a/EpiAware/docs/src/showcase/replications/mishra-2020/index.jl b/EpiAware/docs/src/showcase/replications/mishra-2020/index.jl index e9eb6e5ce..c30b1d893 100644 --- a/EpiAware/docs/src/showcase/replications/mishra-2020/index.jl +++ b/EpiAware/docs/src/showcase/replications/mishra-2020/index.jl @@ -53,16 +53,6 @@ This tutorial introduces the basic functionality of `EpiAware`. `EpiAware` is a It is common to conceptualise the generative process of public health data, e.g a time series of reported cases of an infectious pathogen, in a modular way. For example, it is common to abstract the underlying latent infection process away from downstream issues of observation, or to treat quanitites such as the time-varying reproduction number as being itself generated as a random process. `EpiAware` is built using the [`DynamicPPL`](https://github.com/TuringLang/DynamicPPL.jl) probabilistic programming domain-specific language, which is part of the [`Turing`](https://turinglang.org/dev/docs/using-turing/guide/) PPL. The structural concept behind `EpiAware` is that each module of an epidemiological model is a self-contained `Turing` [`Model`](https://turinglang.org/DynamicPPL.jl/stable/api/#DynamicPPL.Model-Tuple{}); that is each module is an object that can be conditioned on observable data and sampled from. A complete `EpiAware` model is the composition of these objects using the [`@submodel`](https://turinglang.org/DynamicPPL.jl/stable/api/#DynamicPPL.@submodel) macro. - -## Pluto code blocks -Note that `Pluto.jl` notebooks operate on single lines of code or code blocks encapsulated by `let ... end` and `begin ... end`. The reason is that `Pluto` notebooks are reactive, and re-run downstream code after changes with downstreaming determined by a tree of dependent code blocks. If you are running this example from the REPL, you can either use the code blocks and/or run each line individually. - -_NB:_ The difference between `let ... end` blocks and `begin ... end` blocks are that the `let ... end` type of code block only adds the final output/return value of the block to scope, like an anonymous function, whereas `begin ... end` executes each line and adds defined variables to scope. - -## Environment for this notebook and running it from the REPL -This page is generated after running an underlying `Pluto.jl` notebook, using a Julia environment located in the `EpiAware/docs` folder of the repository and checking-out the latest version of `EpiAware` directly from its source code using `Pkg.develop`. The reason for this is that when committing a change to `EpiAware` we want the website to be built with the proposed branch of `EpiAware` as part of our checking before merging. - -If you are trying out this code from REPL after installing `EpiAware` then your REPL will offer you the chance to install each of the dependencies upon evaluating `using SomePackage` for a package `SomePackage` that is not available in your current active environment. " # ╔═╡ 27d73202-a93e-4471-ab50-d59345304a0b