diff --git a/.github/workflows/document-EpiAware.yaml b/.github/workflows/document-EpiAware.yaml new file mode 100644 index 000000000..4039ef4c9 --- /dev/null +++ b/.github/workflows/document-EpiAware.yaml @@ -0,0 +1,30 @@ +name: Documenter +on: + push: + branches: main + tags: [v*] + pull_request: + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + Documenter: + permissions: + contents: write + statuses: write + name: Documentation + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + sparse-checkout: EpiAware + sparse-checkout-cone-mode: false + - name: Move EpiAware to root + run: mv EpiAware/* . + - uses: julia-actions/cache@v1 + - uses: julia-actions/julia-buildpkg@v1 + - uses: julia-actions/julia-docdeploy@v1 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/.gitignore b/.gitignore index c52aed962..ffa29724b 100644 --- a/.gitignore +++ b/.gitignore @@ -3,7 +3,7 @@ # Julia **/Manifest.toml - +**/*_files # Data *.csv *.tsv @@ -62,7 +62,6 @@ dist/ downloads/ eggs/ .eggs/ -lib/ lib64/ parts/ sdist/ @@ -256,9 +255,6 @@ vignettes/*.pdf # R Environment Variables .Renviron -# pkgdown site -docs/ - # translation temp files po/*~ diff --git a/EpiAware/.gitignore b/EpiAware/.gitignore index 0bea468c2..1f2e36495 100644 --- a/EpiAware/.gitignore +++ b/EpiAware/.gitignore @@ -4,7 +4,8 @@ # such, it should not be committed for packages, but should be committed for # applications that require a static environment. **/Manifest.toml -docs +docs/build +!docs/lib/* # Data *.csv diff --git a/EpiAware/CHANGELOG.md b/EpiAware/CHANGELOG.md new file mode 100644 index 000000000..7e9705ae3 --- /dev/null +++ b/EpiAware/CHANGELOG.md @@ -0,0 +1,12 @@ +# Release notes + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## Unreleased + +### Added + +### Changed + +### Fixed diff --git a/EpiAware/docs/Project.toml b/EpiAware/docs/Project.toml new file mode 100644 index 000000000..3d7eeda93 --- /dev/null +++ b/EpiAware/docs/Project.toml @@ -0,0 +1,4 @@ +[deps] +Changelog = "5217a498-cd5d-4ec6-b8c2-9b85a09b6e3e" +Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4" +EpiAware = "b2eeebe4-5992-4301-9193-7ebc9f62c855" diff --git a/EpiAware/docs/changelog.jl b/EpiAware/docs/changelog.jl new file mode 100644 index 000000000..c6649f3dd --- /dev/null +++ b/EpiAware/docs/changelog.jl @@ -0,0 +1,9 @@ +# Generate a Documenter-friendly changelog from CHANGELOG.md +using Changelog + +Changelog.generate( + Changelog.Documenter(), + joinpath(@__DIR__, "..", "CHANGELOG.md"), + joinpath(@__DIR__, "src", "release-notes.md"); + repo = "JuliaDocs/Documenter.jl" +) diff --git a/EpiAware/docs/make.jl b/EpiAware/docs/make.jl new file mode 100644 index 000000000..edc0449fc --- /dev/null +++ b/EpiAware/docs/make.jl @@ -0,0 +1,22 @@ +using Documenter +using EpiAware + +include("changelog.jl") +include("pages.jl") + +makedocs(; sitename = "EpiAware.jl", + authors = "Samuel Brand, Zachary Susswein, Sam Abbott, and contributors", + clean = true, doctest = true, linkcheck = true, + warnonly = [:docs_block, :missing_docs], + modules = [EpiAware], + pages = pages, + format = Documenter.HTML( + prettyurls = get(ENV, "CI", nothing) == "true" + ) +) + +deploydocs( + repo = "github.com/CDCgov/Rt-without-renewal.git", + target = "build", + push_preview = true +) diff --git a/EpiAware/docs/pages.jl b/EpiAware/docs/pages.jl new file mode 100644 index 000000000..db333fa73 --- /dev/null +++ b/EpiAware/docs/pages.jl @@ -0,0 +1,18 @@ +pages = [ + "EpiAware.jl: Real-time epidemic monitoring" => "index.md", + "Manual" => Any[ + "Guide" => "man/guide.md", + "Examples" => [ + "Getting started" => "man/getting-started.md" + ] + ], + "Reference" => Any[ + "Public API" => "lib/public.md" + ], + "Developers" => [ + "Contributing" => "contributing.md", + "Release checklist" => "checklist.md", + "Internals" => "lib/internals.md" + ], + "release-notes.md" +] diff --git a/EpiAware/docs/src/checklist.md b/EpiAware/docs/src/checklist.md new file mode 100644 index 000000000..775e968c4 --- /dev/null +++ b/EpiAware/docs/src/checklist.md @@ -0,0 +1,35 @@ +# Checklists + +The purpose of this page is to collate a series of checklists for commonly +performed changes to the source code of EpiAware. It has been adapted from `Documenter.jl`. + +In each case, copy the checklist into the description of the pull request. + +## Making a release + +In preparation for a release, use the following checklist. These steps should be performed on a branch with an open pull request, either for a topic branch, or for a new branch `release-1.y.z` ("Release version 1.y.z") if multiple changes have accumulated on the `master` branch since the last release. + +```markdown +## Pre-release + + - [ ] Change the version number in `Project.toml` + * If the release is breaking, increment MAJOR + * If the release adds a new user-visible feature, increment MINOR + * Otherwise (bug-fixes, documentation improvements), increment PATCH + - [ ] Update `CHANGELOG.md`, following the existing style (in particular, make sure that the change log for this version has the correct version number and date). + - [ ] Run `make changelog`, to make sure that all the issue references in `CHANGELOG.md` are up to date. + - [ ] Check that the commit messages in this PR do not contain `[ci skip]` + - [ ] Run https://github.com/JuliaDocs/Documenter.jl/actions/workflows/regression-tests.yml + using a `workflow_dispatch` trigger to check for any changes that broke extensions. + +## The release + + - [ ] After merging the pull request, tag the release. There are two options for this: + + 1. [Comment `[at]JuliaRegistrator register` on the GitHub commit.](https://github.com/JuliaRegistries/Registrator.jl#via-the-github-app) + 2. Use [JuliaHub's package registration feature](https://help.juliahub.com/juliahub/stable/contribute/#registrator) to trigger the registration. + + Either of those should automatically publish a new version to the Julia registry. + - Once registered, the `TagBot.yml` workflow should create a tag, and rebuild the documentation for this tag. + - These steps can take quite a bit of time (1 hour or more), so don't be surprised if the new documentation takes a while to appear. +``` diff --git a/EpiAware/docs/src/contributing.md b/EpiAware/docs/src/contributing.md new file mode 100644 index 000000000..d54426632 --- /dev/null +++ b/EpiAware/docs/src/contributing.md @@ -0,0 +1,41 @@ +# Contributing + +This page details the some of the guidelines that should be followed when contributing to this package. It is adapted from `Documenter.jl`. + +## Branches + +`release-*` branches are used for tagged minor versions of this package. This follows the same approach used in the main Julia repository, albeit on a much more modest scale. + +Please open pull requests against the `master` branch rather than any of the `release-*` branches whenever possible. + +### Backports + +Bug fixes are backported to the `release-*` branches using `git cherry-pick -x` by a EpiAware member and will become available in point releases of that particular minor version of the package. + +Feel free to nominate commits that should be backported by opening an issue. Requests for new point releases to be tagged in `METADATA.jl` can also be made in the same way. + +### `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. + +## Style Guide + +Follow the style of the surrounding text when making changes. When adding new features please try to stick to the following points whenever applicable. This project follows the +[SciML style guide](https://github.com/SciML/SciMLStyle). + +## Tests + +### Unit tests + +As is conventional for Julia packages, unit tests are located at `test/*.jl` with the entrypoint +`test/runtests.jl`. + +### End to end testing + +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. diff --git a/EpiAware/docs/src/index.md b/EpiAware/docs/src/index.md new file mode 100644 index 000000000..a9b7be685 --- /dev/null +++ b/EpiAware/docs/src/index.md @@ -0,0 +1,36 @@ +# EpiAware.jl + +*Infectious disease situational awareness modelling toolkit for Julia.* + +A package for building and fitting situational awareness models for infectious diseases. The package is designed to be flexible and extensible, and to provide a consistent interface for fitting and simulating models. + +## Package Features + +- **Flexible**: The package is designed to be flexible and extensible, and to provide a consistent interface for fitting and simulating models. +- **Modular**: The package is designed to be modular, with a clear separation between the model and the data. +- **Extensible**: The package is designed to be extensible, with a clear separation between the model and the data. +- **Consistent**: The package is designed to provide a consistent interface for fitting and simulating models. +- **Efficient**: The package is designed to be efficient, with a clear separation between the model and the data. + +See the [Index](@ref main-index) for the complete list of documented functions and types. + +## Manual Outline + +```@contents +Pages = [ + "man/contributing.md", +] +Depth = 1 +``` + +## Library Outline + +```@contents +Pages = ["lib/public.md", "lib/internals.md"] +``` + +### [Index](@id main-index) + +```@index +Pages = ["lib/public.md"] +``` diff --git a/EpiAware/docs/src/lib/internals.md b/EpiAware/docs/src/lib/internals.md new file mode 100644 index 000000000..57ae28f36 --- /dev/null +++ b/EpiAware/docs/src/lib/internals.md @@ -0,0 +1,23 @@ +# internal Documentation + +Documentation for `EpiAware.jl`'s internal interface. + +## Contents + +```@contents +Pages = ["internal.md"] +Depth = 2:2 +``` + +## Index + +```@index +Pages = ["internals.md"] +``` + +## Internal API + +```@autodocs +Modules = [EpiAware] +Public = false +``` diff --git a/EpiAware/docs/src/lib/public.md b/EpiAware/docs/src/lib/public.md new file mode 100644 index 000000000..2055c84be --- /dev/null +++ b/EpiAware/docs/src/lib/public.md @@ -0,0 +1,20 @@ +# Public Documentation + +Documentation for `EpiAware.jl`'s public interface. + +See the Internals section of the manual for internal package docs covering all submodules. + +## Contents + +```@contents +Pages = ["public.md"] +Depth = 2:2 +``` + +## Index + +```@index +Pages = ["public.md"] +``` + +## Public API diff --git a/EpiAware/docs/src/man/getting-started.md b/EpiAware/docs/src/man/getting-started.md new file mode 100644 index 000000000..e69de29bb diff --git a/EpiAware/docs/src/man/guide.md b/EpiAware/docs/src/man/guide.md new file mode 100644 index 000000000..e69de29bb diff --git a/EpiAware/docs/src/release-notes.md b/EpiAware/docs/src/release-notes.md new file mode 100644 index 000000000..9a75d1049 --- /dev/null +++ b/EpiAware/docs/src/release-notes.md @@ -0,0 +1,16 @@ +```@meta +EditURL = "https://github.com/JuliaDocs/Documenter.jl/blob/master/CHANGELOG.md" +``` + +# Release notes + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## Unreleased + +### Added + +### Changed + +### Fixed diff --git a/EpiAware/docs/versions.js b/EpiAware/docs/versions.js new file mode 100644 index 000000000..6cc415a92 --- /dev/null +++ b/EpiAware/docs/versions.js @@ -0,0 +1,3 @@ +// This is here just to make the version selector show up when you build Documenter's +// manual locally when developing / debugging. +var DOC_VERSIONS = ["build"]; diff --git a/EpiAware/src/EpiAware.jl b/EpiAware/src/EpiAware.jl index e7ddec694..e998ac06a 100644 --- a/EpiAware/src/EpiAware.jl +++ b/EpiAware/src/EpiAware.jl @@ -40,19 +40,23 @@ $(EXPORTS) """ module EpiAware -using Distributions, Turing, LogExpFunctions, LinearAlgebra, SparseArrays, Random, - ReverseDiff, Optim, Parameters, QuadGK, DataFramesMeta, DocStringExtensions +using Distributions, Turing, LogExpFunctions, LinearAlgebra, SparseArrays, + Random, ReverseDiff, Optim, Parameters, QuadGK, DataFramesMeta, + DocStringExtensions -# Exported utilities -export create_discrete_pmf, spread_draws, scan +# Exported abstract types +export AbstractModel, AbstractEpiModel, AbstractLatentModel, + AbstractObservationModel # Exported types -export EpiData, Renewal, ExpGrowthRate, DirectInfections, AbstractModel, - AbstractEpiModel, AbstractLatentModel, AbstractObservationModel +export EpiData, Renewal, ExpGrowthRate, DirectInfections, RandomWalk # Exported Turing model constructors export make_epi_aware +# Exported utilities +export create_discrete_pmf, spread_draws, scan + include("abstract-types.jl") include("epi-models.jl") include("utilities.jl")