Merge pull request #93 from CDCgov/add-documenter

Add the basic structure of documenter

.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 }}

.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/*~
 

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

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

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"

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"
+)

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
+)

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"
+]

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.
+```

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.

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"]
+```

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
+```

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

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

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"];

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")