Merge branch 'main' of https://github.com/simonsteiger/RheumaComposit…

…es.jl

.github/workflows/documentation.yml

@@ -18,8 +18,8 @@ jobs:
       contents: write
       statuses: write
     steps:
-      - uses: actions/checkout@v2
-      - uses: julia-actions/setup-julia@v1
+      - uses: actions/checkout@v4
+      - uses: julia-actions/setup-julia@v2
         with:
           version: '1'
       - uses: julia-actions/julia-buildpkg@v1

README.md

@@ -1,53 +1,44 @@
 # RheumaComposites.jl
 
 [![Build Status](https://github.com/simonsteiger/RheumaComposites.jl/actions/workflows/CI.yml/badge.svg?branch=main)](https://github.com/simonsteiger/RheumaComposites.jl/actions/workflows/CI.yml?query=branch%3Amain)
+[![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://simonsteiger.github.io/RheumaComposites.jl/dev/)
 
-This package implements the most common composite scores used for evaluating disease activity across different rheumatic diseases:
-
-- DAS28ESR
-- DAS28CRP
-- SDAI
-- CDAI
-- ACR / EULAR Boolean remission
-- Revised ACR / EULAR Boolean remission
-- Three-item ACR / EULAR Boolean remission
-
-In addition to composite measures, this package allows testing for further remission definitions:
-
-- SJC28 remission
-- PGA remission
+A Julia package for composite scores used in Rheumatology.
 
 ## Getting started
 
-Since this package is not currently registered with the Julia package registry, you have to install it via url:
+This package is not yet registered with the Julia package registry, so you have to install it via url:
 
 ```julia
 import Pkg
 Pkg.add(url="https://github.com/simonsteiger/RheumaComposites.jl")
 ```
 
-## Examples
-
-This package is effectively undocumented right now, so I hope that these basic examples give an idea of its use:
+Now you're ready to start working with composite scores:
 
 ```julia
-using RheumaComposites
-
-das28 = DAS28ESR(t28=4, s28=3, pga=41u"mm", apr=19u"mm/hr");
-
+using RheumaComposites, Unitful
+das28 = DAS28ESR(t28=4, s28=3, pga=41u"mm", apr=19u"mm/hr")
 score(das28)
-# 4.24
-
 isremission(das28)
-# false
+categorise(das28)
 ```
 
-This package uses [Unitful.jl](https://painterqubits.github.io/Unitful.jl/stable/) to ensure correctness between different measurement systems, such as PGA measured in mm or cm or CRP measured in mg/dL or mg/L.
+Have a look at the [documentation](https://simonsteiger.github.io/RheumaComposites.jl/dev/) for more examples!
+
+## Supported composites
+
+This package currently supports the following composites:
 
-## Resources
+| Rheumatoid Arthritis | Psoriatric Arthritis | Spondyloarthritis | Lupus | ... |
+|:---------------------|:---------------------|:------------------|:------|:----|
+| DAS28                |                      |                   |       | ... |
+| SDAI                 |                      |                   |       | ... |
+| CDAI                 |                      |                   |       | ... |
+| Boolean remission    |                      |                   |       | ... |
 
-Not much here yet!
+Additional subtypes and modifications of these composites are available, e.g., the DAS28CRP or the Revised Boolean Remission.
 
-The above example generalises to the other constructors, namely `DAS28CRP`, `SDAI`, `BooleanRemission`, and its modifications `revised(x::BooleanRemission)`, `threeitem(x::BooleanRemission)`.
+## Contributing
 
-**NOTE**: This project is a very early work in progress and far from complete. For many functions, documentation is still missing.
+If you spot a bug or want to ask for a new feature, please [open an issue](https://github.com/simonsteiger/RheumaComposites.jl/issues) on the GitHub repository.

docs/Project.toml

@@ -1,6 +1,8 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 DocumenterInterLinks = "d12716ef-a0f6-4df4-a9f1-a5a34e75c656"
+DocumenterVitepress = "4710194d-e776-4893-9690-8d956a29c365"
+Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
 RheumaComposites = "579811c7-86f9-4c5f-9fea-fbfdecde0101"
 Unitful = "1986cc42-f94f-5a68-af5c-568840ba703d"
 

docs/make.jl

@@ -1,5 +1,7 @@
 using Documenter
 using DocumenterInterLinks
+using DocumenterVitepress
+using Literate
 using RheumaComposites
 using Unitful
 
@@ -10,10 +12,58 @@ links = InterLinks(
     "Unitful" => "https://painterqubits.github.io/Unitful.jl/stable/objects.inv",
 )
 
-makedocs(;
+open(joinpath(joinpath(@__DIR__, "src"), "index.md"), "w") do io
+    println(
+        io,
+        """
+        ```@meta
+        EditURL = "https://github.com/simonsteiger/RheumaComposites.jl/blob/main/README.md"
+        ```
+        """,
+    )
+    for line in eachline(joinpath(dirname(@__DIR__), "README.md"))
+        println(io, line)
+    end
+end
+
+examples_jl_path = joinpath(dirname(@__DIR__), "examples")
+examples_md_path = joinpath(@__DIR__, "src", "examples")
+
+for file in readdir(examples_md_path)
+    if endswith(file, ".md")
+        rm(joinpath(examples_md_path, file))
+    end
+end
+
+for file in readdir(examples_jl_path)
+    Literate.markdown(joinpath(examples_jl_path, file), examples_md_path)
+end
+
+pages = [
+    "Home" => "index.md",
+    "Tutorials" => [
+        "Basics" => joinpath("examples", "basics.md")
+    ],
+    "API reference" => "api.md",
+]
+
+Documenter.makedocs(;
     sitename="RheumaComposites.jl",
+    authors="Simon Steiger",
     modules=[RheumaComposites],
+    format=DocumenterVitepress.MarkdownVitepress(;
+        repo="https://github.com/simonsteiger/RheumaComposites.jl",
+        deploy_url="https://simonsteiger.github.io/RheumaComposites.jl",
+        devbranch="main",
+        devurl="dev",
+    ),
+    pages=pages,
     plugins=[links],
+    pagesonly=true,
 )
 
-deploydocs(; repo="github.com/simonsteiger/RheumaComposites.jl", devbranch="main")
+deploydocs(;
+    repo="github.com/simonsteiger/RheumaComposites.jl",
+    target="build",
+    devbranch="main"
+)

docs/src/api.md

@@ -0,0 +1,57 @@
+# API reference
+
+```@docs
+RheumaComposites
+```
+
+## Types
+
+```@docs
+AbstractComposite
+ContinuousComposite
+BooleanComposite
+ModifiedComposite
+DAS28
+DAS28ESR
+DAS28CRP
+SDAI
+CDAI
+Faceted
+BooleanRemission
+Revised
+ThreeItem
+AbstractComponent
+PGA
+SJC28
+```
+
+## Interface
+
+```@docs
+t28
+s28
+pga
+apr
+ega
+crp
+```
+
+## Functions
+
+```@docs
+intercept
+weight
+score
+isremission
+decompose
+categorise
+faceted
+revised
+threeitem
+value
+```
+
+## Index
+
+```@index
+```

docs/src/examples/basics.md

@@ -0,0 +1,74 @@
+```@meta
+EditURL = "../../../examples/basics.jl"
+```
+
+# Creating Composites
+
+This tutorial shows you how to set up different composite scores.
+
+````@example basics
+using RheumaComposites
+````
+
+Creating composites requires specifying the units of some components.
+
+This protects us from accidentally specifying a DAS28 score on a 0-10 cm visual analogue scale (VAS), or vice versa, an SDAI on a 0-100 mm (VAS).
+The only exception are joint counts, which are simply integers.
+
+We will use [`Unitful.jl`](https://painterqubits.github.io/Unitful.jl/stable/) for specifying units throughout.
+
+````@example basics
+using Unitful
+````
+
+Creating units is easy thanks to the [`@u_str`](https://painterqubits.github.io/Unitful.jl/stable/manipulations/#Unitful.@u_str) macro.
+
+````@example basics
+18u"mm", 64u"mg/L"
+````
+
+Converting a unitless value stored in a variable is simple, too:
+
+````@example basics
+x = 7;
+x * u"cm"
+````
+
+Under the hood, the composites will be converted to the unit matching scoring weights and remission cutoffs.
+This means that you do not have to remember that SDAI requires a 0-10 cm VAS scale and C-reactive protein in mg/dL, while the DAS28 requires millimeters and mg/L.
+
+Let's try this by creating a DAS28CRP composite with patient's global assessment measured in centimeters:
+
+````@example basics
+das28_cm = DAS28CRP(t28=1, s28=0, pga=2.2u"cm", apr=4u"mg/L")
+````
+
+As you can see, centimeters were automatically converted to millimeters.
+Providing the same score in millimeters return the same result:
+
+````@example basics
+das28_mm = DAS28CRP(t28=1, s28=0, pga=22u"mm", apr=4u"mg/L")
+score(das28_cm) == score(das28_mm)
+````
+
+This principle holds for all supported composites.
+
+## Components
+
+If you are not sure about the component names of a composite, you can check the docstring of that composite for guidance.
+To see the docstring, first hit `?` in the REPL, then type the name of the composite, and hit enter.
+
+This is all we need to explore the most important aspects of many different composite scores!
+
+````@example basics
+sdai = SDAI(s28=3, t28=4, pga=34u"mm", ega=28u"mm", crp=21u"mg/L")
+````
+
+````@example basics
+score(sdai), isremission(sdai), categorise(sdai)
+````
+
+---
+
+*This page was generated using [Literate.jl](https://github.com/fredrikekre/Literate.jl).*
+

docs/src/index.md

@@ -1,57 +1,48 @@
-# API reference
-
-```@docs
-RheumaComposites
+```@meta
+EditURL = "https://github.com/simonsteiger/RheumaComposites.jl/blob/main/README.md"
 ```
 
-## Types
-
-```@docs
-AbstractComposite
-ContinuousComposite
-BooleanComposite
-ModifiedComposite
-DAS28
-DAS28ESR
-DAS28CRP
-SDAI
-CDAI
-Faceted
-BooleanRemission
-Revised
-ThreeItem
-AbstractComponent
-PGA
-SJC28
-```
+# RheumaComposites.jl
 
-## Interface
+[![Build Status](https://github.com/simonsteiger/RheumaComposites.jl/actions/workflows/CI.yml/badge.svg?branch=main)](https://github.com/simonsteiger/RheumaComposites.jl/actions/workflows/CI.yml?query=branch%3Amain)
+[![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://simonsteiger.github.io/RheumaComposites.jl/dev/)
 
-```@docs
-t28
-s28
-pga
-apr
-ega
-crp
-```
+A Julia package for composite scores used in Rheumatology.
 
-## Functions
-
-```@docs
-intercept
-weight
-score
-isremission
-decompose
-categorise
-faceted
-revised
-threeitem
-value
+## Getting started
+
+This package is not yet registered with the Julia package registry, so you have to install it via url:
+
+```julia
+import Pkg
+Pkg.add(url="https://github.com/simonsteiger/RheumaComposites.jl")
 ```
 
-## Index
+Now you're ready to start working with composite scores:
 
-```@index
+```julia
+using RheumaComposites, Unitful
+das28 = DAS28ESR(t28=4, s28=3, pga=41u"mm", apr=19u"mm/hr")
+score(das28)
+isremission(das28)
+categorise(das28)
 ```
+
+Have a look at the [documentation](https://simonsteiger.github.io/RheumaComposites.jl/dev/) for more examples!
+
+## Supported composites
+
+This package currently supports the following composites:
+
+| Rheumatoid Arthritis | Psoriatric Arthritis | Spondyloarthritis | Lupus | ... |
+|:---------------------|:---------------------|:------------------|:------|:----|
+| DAS28                |                      |                   |       | ... |
+| SDAI                 |                      |                   |       | ... |
+| CDAI                 |                      |                   |       | ... |
+| Boolean remission    |                      |                   |       | ... |
+
+Additional subtypes and modifications of these composites are available, e.g., the DAS28CRP or the Revised Boolean Remission.
+
+## Contributing
+
+If you spot a bug or want to ask for a new feature, please [open an issue](https://github.com/simonsteiger/RheumaComposites.jl/issues) on the GitHub repository.