From 0fc488ed4db3a1ef2deaad1fa94e3bd375dab019 Mon Sep 17 00:00:00 2001 From: Sam Date: Fri, 23 Feb 2024 17:54:52 +0000 Subject: [PATCH 01/20] add the basic structure of documenter --- .gitignore | 3 --- EpiAware/.gitignore | 2 +- EpiAware/docs/Project.toml | 3 +++ EpiAware/docs/make.jl | 11 +++++++++++ EpiAware/docs/pages.jl | 3 +++ EpiAware/docs/src/index.md | 0 6 files changed, 18 insertions(+), 4 deletions(-) create mode 100644 EpiAware/docs/Project.toml create mode 100644 EpiAware/docs/make.jl create mode 100644 EpiAware/docs/pages.jl create mode 100644 EpiAware/docs/src/index.md diff --git a/.gitignore b/.gitignore index c52aed962..5e1e13d29 100644 --- a/.gitignore +++ b/.gitignore @@ -256,9 +256,6 @@ vignettes/*.pdf # R Environment Variables .Renviron -# pkgdown site -docs/ - # translation temp files po/*~ diff --git a/EpiAware/.gitignore b/EpiAware/.gitignore index 0bea468c2..909a297ac 100644 --- a/EpiAware/.gitignore +++ b/EpiAware/.gitignore @@ -4,7 +4,7 @@ # such, it should not be committed for packages, but should be committed for # applications that require a static environment. **/Manifest.toml -docs +docs/build # Data *.csv diff --git a/EpiAware/docs/Project.toml b/EpiAware/docs/Project.toml new file mode 100644 index 000000000..11e6cdf13 --- /dev/null +++ b/EpiAware/docs/Project.toml @@ -0,0 +1,3 @@ +[deps] +Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4" +EpiAware = "b2eeebe4-5992-4301-9193-7ebc9f62c855" diff --git a/EpiAware/docs/make.jl b/EpiAware/docs/make.jl new file mode 100644 index 000000000..26cd741e1 --- /dev/null +++ b/EpiAware/docs/make.jl @@ -0,0 +1,11 @@ +using Documenter +using EpiAware + +include("pages.jl") + +makedocs(; sitename = "EpiAware.jl", + authors = "Samuel Brand, Zachary Susswein, and Sam Abbott", + clean = true, doctest = true, linkcheck = true, + warnonly = [:docs_block, :missing_docs], + modules = [EpiAware], + pages = pages) diff --git a/EpiAware/docs/pages.jl b/EpiAware/docs/pages.jl new file mode 100644 index 000000000..058f9fe37 --- /dev/null +++ b/EpiAware/docs/pages.jl @@ -0,0 +1,3 @@ +pages = [ + "EpiAware.jl: Real-time epidemic monitoring" => "index.md" +] diff --git a/EpiAware/docs/src/index.md b/EpiAware/docs/src/index.md new file mode 100644 index 000000000..e69de29bb From b72e0a3722aa24b7712dfc608db19eabe5f0d275 Mon Sep 17 00:00:00 2001 From: Sam Date: Fri, 23 Feb 2024 19:20:59 +0000 Subject: [PATCH 02/20] partial documenter setup --- EpiAware/CHANGELOG.md | 12 ++++++++++++ EpiAware/docs/Project.toml | 1 + EpiAware/docs/make.jl | 10 +++++++++- 3 files changed, 22 insertions(+), 1 deletion(-) create mode 100644 EpiAware/CHANGELOG.md 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 index 11e6cdf13..3d7eeda93 100644 --- a/EpiAware/docs/Project.toml +++ b/EpiAware/docs/Project.toml @@ -1,3 +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/make.jl b/EpiAware/docs/make.jl index 26cd741e1..58d02b55e 100644 --- a/EpiAware/docs/make.jl +++ b/EpiAware/docs/make.jl @@ -3,8 +3,16 @@ using EpiAware include("pages.jl") +# Generate a Documenter-friendly changelog from CHANGELOG.md +Changelog.generate( + Changelog.Documenter(), + joinpath(@__DIR__, "..", "CHANGELOG.md"), + joinpath(@__DIR__, "src", "release-notes.md"); + repo = "JuliaDocs/Documenter.jl" +) + makedocs(; sitename = "EpiAware.jl", - authors = "Samuel Brand, Zachary Susswein, and Sam Abbott", + authors = "Samuel Brand, Zachary Susswein, Sam Abbott, and contributors", clean = true, doctest = true, linkcheck = true, warnonly = [:docs_block, :missing_docs], modules = [EpiAware], From 4ea3c1294e578bcd1dfd8d77e6adf7bee0aa3258 Mon Sep 17 00:00:00 2001 From: Sam Date: Thu, 29 Feb 2024 11:45:17 +0000 Subject: [PATCH 03/20] add additional docs structure" --- .gitignore | 2 +- EpiAware/docs/changelog.jl | 7 ++++++ EpiAware/docs/make.jl | 9 +------ EpiAware/docs/src/checklist.md | 35 ++++++++++++++++++++++++++ EpiAware/docs/src/contributing.md | 41 +++++++++++++++++++++++++++++++ EpiAware/docs/versions.js | 3 +++ 6 files changed, 88 insertions(+), 9 deletions(-) create mode 100644 EpiAware/docs/changelog.jl create mode 100644 EpiAware/docs/src/checklist.md create mode 100644 EpiAware/docs/src/contributing.md create mode 100644 EpiAware/docs/versions.js diff --git a/.gitignore b/.gitignore index 5e1e13d29..6f2fcca24 100644 --- a/.gitignore +++ b/.gitignore @@ -3,7 +3,7 @@ # Julia **/Manifest.toml - +**/*_files # Data *.csv *.tsv diff --git a/EpiAware/docs/changelog.jl b/EpiAware/docs/changelog.jl new file mode 100644 index 000000000..652d059cf --- /dev/null +++ b/EpiAware/docs/changelog.jl @@ -0,0 +1,7 @@ +# Generate a Documenter-friendly changelog from CHANGELOG.md +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 index 58d02b55e..5dba402e8 100644 --- a/EpiAware/docs/make.jl +++ b/EpiAware/docs/make.jl @@ -1,16 +1,9 @@ using Documenter using EpiAware +include("changelog.jl") include("pages.jl") -# Generate a Documenter-friendly changelog from CHANGELOG.md -Changelog.generate( - Changelog.Documenter(), - joinpath(@__DIR__, "..", "CHANGELOG.md"), - joinpath(@__DIR__, "src", "release-notes.md"); - repo = "JuliaDocs/Documenter.jl" -) - makedocs(; sitename = "EpiAware.jl", authors = "Samuel Brand, Zachary Susswein, Sam Abbott, and contributors", clean = true, doctest = true, linkcheck = true, 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..fb9789de0 --- /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/JuliaDocs/Documenter.jl/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/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"]; From eea7b723e1be996561601cde28ccd06a1c7da0ad Mon Sep 17 00:00:00 2001 From: Sam Date: Thu, 29 Feb 2024 11:46:31 +0000 Subject: [PATCH 04/20] update link to milestones --- EpiAware/docs/src/contributing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EpiAware/docs/src/contributing.md b/EpiAware/docs/src/contributing.md index fb9789de0..484a1cd01 100644 --- a/EpiAware/docs/src/contributing.md +++ b/EpiAware/docs/src/contributing.md @@ -20,7 +20,7 @@ Feel free to nominate commits that should be backported by opening an issue. Req * 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/JuliaDocs/Documenter.jl/milestones) are used to keep track of which PRs get backported etc. + * Patch version [milestones](https://github.com/CDCgov/EpiAware/milestones) are used to keep track of which PRs get backported etc. ## Style Guide From 98acba60f34b84df0ce57a1793a84eac422376d7 Mon Sep 17 00:00:00 2001 From: Sam Date: Thu, 29 Feb 2024 11:53:20 +0000 Subject: [PATCH 05/20] add more documentation structure --- EpiAware/docs/src/index.md | 36 +++++++++++++++++++++ EpiAware/docs/src/{ => man}/contributing.md | 0 2 files changed, 36 insertions(+) rename EpiAware/docs/src/{ => man}/contributing.md (100%) diff --git a/EpiAware/docs/src/index.md b/EpiAware/docs/src/index.md index e69de29bb..a9b7be685 100644 --- a/EpiAware/docs/src/index.md +++ 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/contributing.md b/EpiAware/docs/src/man/contributing.md similarity index 100% rename from EpiAware/docs/src/contributing.md rename to EpiAware/docs/src/man/contributing.md From 72a2a3dd16eeb7a5dcce05fa7da72e5de84b9ef2 Mon Sep 17 00:00:00 2001 From: Sam Date: Thu, 29 Feb 2024 14:12:24 +0000 Subject: [PATCH 06/20] add workflow for GitHub Actions to deploy docs --- .github/workflows/document-EpiAware.yaml | 30 ++++++++++++++++++++++++ 1 file changed, 30 insertions(+) create mode 100644 .github/workflows/document-EpiAware.yaml diff --git a/.github/workflows/document-EpiAware.yaml b/.github/workflows/document-EpiAware.yaml new file mode 100644 index 000000000..0442c7183 --- /dev/null +++ b/.github/workflows/document-EpiAware.yaml @@ -0,0 +1,30 @@ +name: Documenter +on: + push: + branches: [main, master] + 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 }} From b0352dd23fd74038681e4482d26f841826fc0d2b Mon Sep 17 00:00:00 2001 From: Sam Date: Thu, 29 Feb 2024 16:33:56 +0000 Subject: [PATCH 07/20] missing . in mv --- .github/workflows/document-EpiAware.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/document-EpiAware.yaml b/.github/workflows/document-EpiAware.yaml index 0442c7183..89301f5fb 100644 --- a/.github/workflows/document-EpiAware.yaml +++ b/.github/workflows/document-EpiAware.yaml @@ -22,7 +22,7 @@ jobs: sparse-checkout: EpiAware sparse-checkout-cone-mode: false - name: Move EpiAware to root - run: mv EpiAware/* + run: mv EpiAware/* . - uses: julia-actions/cache@v1 - uses: julia-actions/julia-buildpkg@v1 - uses: julia-actions/julia-docdeploy@v1 From 5dd617374813eeef0376b5675931fa3b283809a3 Mon Sep 17 00:00:00 2001 From: Sam Date: Thu, 29 Feb 2024 16:35:00 +0000 Subject: [PATCH 08/20] remove reference to master in document action --- .github/workflows/document-EpiAware.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/document-EpiAware.yaml b/.github/workflows/document-EpiAware.yaml index 89301f5fb..4039ef4c9 100644 --- a/.github/workflows/document-EpiAware.yaml +++ b/.github/workflows/document-EpiAware.yaml @@ -1,7 +1,7 @@ name: Documenter on: push: - branches: [main, master] + branches: main tags: [v*] pull_request: From 6c1a000ad2e7fd53d82e13395f40b6c119a46030 Mon Sep 17 00:00:00 2001 From: Sam Date: Thu, 29 Feb 2024 17:11:55 +0000 Subject: [PATCH 09/20] check changelog --- EpiAware/docs/changelog.jl | 2 ++ EpiAware/docs/src/release-notes.md | 0 2 files changed, 2 insertions(+) create mode 100644 EpiAware/docs/src/release-notes.md diff --git a/EpiAware/docs/changelog.jl b/EpiAware/docs/changelog.jl index 652d059cf..c6649f3dd 100644 --- a/EpiAware/docs/changelog.jl +++ b/EpiAware/docs/changelog.jl @@ -1,4 +1,6 @@ # Generate a Documenter-friendly changelog from CHANGELOG.md +using Changelog + Changelog.generate( Changelog.Documenter(), joinpath(@__DIR__, "..", "CHANGELOG.md"), diff --git a/EpiAware/docs/src/release-notes.md b/EpiAware/docs/src/release-notes.md new file mode 100644 index 000000000..e69de29bb From a443269b0fc40bdbc9f5ade037376d50627aca92 Mon Sep 17 00:00:00 2001 From: Sam Date: Thu, 29 Feb 2024 17:35:10 +0000 Subject: [PATCH 10/20] update milestones link --- EpiAware/docs/src/man/contributing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EpiAware/docs/src/man/contributing.md b/EpiAware/docs/src/man/contributing.md index 484a1cd01..d54426632 100644 --- a/EpiAware/docs/src/man/contributing.md +++ b/EpiAware/docs/src/man/contributing.md @@ -20,7 +20,7 @@ Feel free to nominate commits that should be backported by opening an issue. Req * 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/EpiAware/milestones) are used to keep track of which PRs get backported etc. + * Patch version [milestones](https://github.com/CDCgov/Rt-without-renewal/milestones) are used to keep track of which PRs get backported etc. ## Style Guide From 67a4d965578e391e06e4d84d93e0e8800bd57050 Mon Sep 17 00:00:00 2001 From: Sam Date: Thu, 29 Feb 2024 17:36:42 +0000 Subject: [PATCH 11/20] make links work both locally and on CI --- EpiAware/docs/make.jl | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/EpiAware/docs/make.jl b/EpiAware/docs/make.jl index 5dba402e8..7c81f38b0 100644 --- a/EpiAware/docs/make.jl +++ b/EpiAware/docs/make.jl @@ -9,4 +9,8 @@ makedocs(; sitename = "EpiAware.jl", clean = true, doctest = true, linkcheck = true, warnonly = [:docs_block, :missing_docs], modules = [EpiAware], - pages = pages) + pages = pages, + format = Documenter.HTML( + prettyurls = get(ENV, "CI", nothing) == "true" + ) +) From ed34a6827699ea24cd2affd3b309c278dc866c27 Mon Sep 17 00:00:00 2001 From: Sam Date: Thu, 29 Feb 2024 22:44:05 +0000 Subject: [PATCH 12/20] continue to build out docs structure --- EpiAware/.gitignore | 1 + EpiAware/docs/make.jl | 6 ++++++ EpiAware/docs/pages.jl | 20 +++++++++++++++++++- EpiAware/docs/src/{man => }/contributing.md | 0 EpiAware/docs/src/man/getting-started.md | 0 EpiAware/docs/src/man/guide.md | 0 EpiAware/docs/src/release-notes.md | 16 ++++++++++++++++ 7 files changed, 42 insertions(+), 1 deletion(-) rename EpiAware/docs/src/{man => }/contributing.md (100%) create mode 100644 EpiAware/docs/src/man/getting-started.md create mode 100644 EpiAware/docs/src/man/guide.md diff --git a/EpiAware/.gitignore b/EpiAware/.gitignore index 909a297ac..3a8bedcad 100644 --- a/EpiAware/.gitignore +++ b/EpiAware/.gitignore @@ -5,6 +5,7 @@ # applications that require a static environment. **/Manifest.toml docs/build +!docs/lib # Data *.csv diff --git a/EpiAware/docs/make.jl b/EpiAware/docs/make.jl index 7c81f38b0..edc0449fc 100644 --- a/EpiAware/docs/make.jl +++ b/EpiAware/docs/make.jl @@ -14,3 +14,9 @@ makedocs(; sitename = "EpiAware.jl", 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 index 058f9fe37..ed7a167b0 100644 --- a/EpiAware/docs/pages.jl +++ b/EpiAware/docs/pages.jl @@ -1,3 +1,21 @@ pages = [ - "EpiAware.jl: Real-time epidemic monitoring" => "index.md" + "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.md", + "checklists.md", + "Internals" => map( + s -> "lib/internals/$(s)", + sort(readdir(joinpath(@__DIR__, "src/lib/internals"))) + ) + ], + "release-notes.md" ] diff --git a/EpiAware/docs/src/man/contributing.md b/EpiAware/docs/src/contributing.md similarity index 100% rename from EpiAware/docs/src/man/contributing.md rename to EpiAware/docs/src/contributing.md 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 index e69de29bb..9a75d1049 100644 --- a/EpiAware/docs/src/release-notes.md +++ 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 From 3f3e2431d6029f16978b7a52d97a5faf8c4eb875 Mon Sep 17 00:00:00 2001 From: Sam Date: Thu, 29 Feb 2024 22:45:06 +0000 Subject: [PATCH 13/20] update .gitignore --- EpiAware/.gitignore | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EpiAware/.gitignore b/EpiAware/.gitignore index 3a8bedcad..1f2e36495 100644 --- a/EpiAware/.gitignore +++ b/EpiAware/.gitignore @@ -5,7 +5,7 @@ # applications that require a static environment. **/Manifest.toml docs/build -!docs/lib +!docs/lib/* # Data *.csv From 5098e756a1b7f73d2e6545827d2f6e583cb75b4f Mon Sep 17 00:00:00 2001 From: Sam Date: Thu, 29 Feb 2024 22:45:50 +0000 Subject: [PATCH 14/20] add lib docs --- .gitignore | 1 - EpiAware/docs/src/lib/internals.md | 0 EpiAware/docs/src/lib/public.md | 0 3 files changed, 1 deletion(-) create mode 100644 EpiAware/docs/src/lib/internals.md create mode 100644 EpiAware/docs/src/lib/public.md diff --git a/.gitignore b/.gitignore index 6f2fcca24..ffa29724b 100644 --- a/.gitignore +++ b/.gitignore @@ -62,7 +62,6 @@ dist/ downloads/ eggs/ .eggs/ -lib/ lib64/ parts/ sdist/ diff --git a/EpiAware/docs/src/lib/internals.md b/EpiAware/docs/src/lib/internals.md new file mode 100644 index 000000000..e69de29bb diff --git a/EpiAware/docs/src/lib/public.md b/EpiAware/docs/src/lib/public.md new file mode 100644 index 000000000..e69de29bb From 5c906b92fa21e492e2ccc83b3ff73fbbafb7dd61 Mon Sep 17 00:00:00 2001 From: Sam Date: Thu, 29 Feb 2024 22:51:19 +0000 Subject: [PATCH 15/20] make public interface --- EpiAware/docs/src/lib/public.md | 50 +++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) diff --git a/EpiAware/docs/src/lib/public.md b/EpiAware/docs/src/lib/public.md index e69de29bb..55c42c143 100644 --- a/EpiAware/docs/src/lib/public.md +++ b/EpiAware/docs/src/lib/public.md @@ -0,0 +1,50 @@ +# 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"] +``` +## Modules + +```@docs +EpiAware +``` + +## Abstract types + +```@docs +AbstractModel +AbstractEpiModel +AbstractLatentModel +AbstractObservationModel +``` + +## Types + +```@docs +EpiData +Renewal +ExpGrowthRate +DirectInfections +``` + +## Functions + +```@docs +make_epi_aware +create_discrete_pmf +spread_draws +scan +``` From e9e8deada6b0ae2fce7c2153f10c4d4d4b310d21 Mon Sep 17 00:00:00 2001 From: Sam Date: Thu, 29 Feb 2024 22:55:08 +0000 Subject: [PATCH 16/20] make exports a little more logical --- EpiAware/docs/src/lib/public.md | 1 + EpiAware/src/EpiAware.jl | 16 ++++++++++------ 2 files changed, 11 insertions(+), 6 deletions(-) diff --git a/EpiAware/docs/src/lib/public.md b/EpiAware/docs/src/lib/public.md index 55c42c143..4a89ab72a 100644 --- a/EpiAware/docs/src/lib/public.md +++ b/EpiAware/docs/src/lib/public.md @@ -38,6 +38,7 @@ EpiData Renewal ExpGrowthRate DirectInfections +RandomWalk ``` ## Functions 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") From 8f48eb7ea834f8bb43bcd899f5c0218968e25480 Mon Sep 17 00:00:00 2001 From: Sam Date: Thu, 29 Feb 2024 23:04:37 +0000 Subject: [PATCH 17/20] finalise docs structure --- EpiAware/docs/pages.jl | 5 +---- EpiAware/docs/src/lib/internals.md | 23 ++++++++++++++++++++ EpiAware/docs/src/lib/public.md | 34 ++++-------------------------- 3 files changed, 28 insertions(+), 34 deletions(-) diff --git a/EpiAware/docs/pages.jl b/EpiAware/docs/pages.jl index ed7a167b0..4bdf11e1c 100644 --- a/EpiAware/docs/pages.jl +++ b/EpiAware/docs/pages.jl @@ -12,10 +12,7 @@ pages = [ "Developers" => [ "contributing.md", "checklists.md", - "Internals" => map( - s -> "lib/internals/$(s)", - sort(readdir(joinpath(@__DIR__, "src/lib/internals"))) - ) + "Internals" => "lib/internals.md" ], "release-notes.md" ] diff --git a/EpiAware/docs/src/lib/internals.md b/EpiAware/docs/src/lib/internals.md index e69de29bb..57ae28f36 100644 --- a/EpiAware/docs/src/lib/internals.md +++ 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 index 4a89ab72a..1ddcd80c3 100644 --- a/EpiAware/docs/src/lib/public.md +++ b/EpiAware/docs/src/lib/public.md @@ -16,36 +16,10 @@ Depth = 2:2 ```@index Pages = ["public.md"] ``` -## Modules -```@docs -EpiAware -``` - -## Abstract types - -```@docs -AbstractModel -AbstractEpiModel -AbstractLatentModel -AbstractObservationModel -``` - -## Types - -```@docs -EpiData -Renewal -ExpGrowthRate -DirectInfections -RandomWalk -``` - -## Functions +## Public API -```@docs -make_epi_aware -create_discrete_pmf -spread_draws -scan +```@autodocs +Modules = [EpiAware] +Private = false ``` From 731534a5a01b6f58a5a29e4e2b9dccc07d3df888 Mon Sep 17 00:00:00 2001 From: Sam Date: Thu, 29 Feb 2024 23:09:41 +0000 Subject: [PATCH 18/20] fix indexx' --- EpiAware/docs/pages.jl | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/EpiAware/docs/pages.jl b/EpiAware/docs/pages.jl index 4bdf11e1c..db333fa73 100644 --- a/EpiAware/docs/pages.jl +++ b/EpiAware/docs/pages.jl @@ -10,8 +10,8 @@ pages = [ "Public API" => "lib/public.md" ], "Developers" => [ - "contributing.md", - "checklists.md", + "Contributing" => "contributing.md", + "Release checklist" => "checklist.md", "Internals" => "lib/internals.md" ], "release-notes.md" From e2144e9478bba72b54723e4561a7e9068cb85c93 Mon Sep 17 00:00:00 2001 From: Sam Date: Thu, 29 Feb 2024 23:17:16 +0000 Subject: [PATCH 19/20] don't try and autodoc until coverage of exported code improves --- EpiAware/docs/src/lib/public.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/EpiAware/docs/src/lib/public.md b/EpiAware/docs/src/lib/public.md index 1ddcd80c3..89f78f445 100644 --- a/EpiAware/docs/src/lib/public.md +++ b/EpiAware/docs/src/lib/public.md @@ -18,8 +18,8 @@ Pages = ["public.md"] ``` ## Public API - + From f7c5519696163baaa6f8a76e3124de94e447faf0 Mon Sep 17 00:00:00 2001 From: Sam Date: Thu, 29 Feb 2024 23:23:26 +0000 Subject: [PATCH 20/20] entirely remove autodocs trigger --- EpiAware/docs/src/lib/public.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/EpiAware/docs/src/lib/public.md b/EpiAware/docs/src/lib/public.md index 89f78f445..2055c84be 100644 --- a/EpiAware/docs/src/lib/public.md +++ b/EpiAware/docs/src/lib/public.md @@ -18,8 +18,3 @@ Pages = ["public.md"] ``` ## Public API -