From bf6e13b6aa3b541c5ff2ea33f598d6e8d1042a55 Mon Sep 17 00:00:00 2001
From: Orestis Ousoultzoglou <xlxs4@protonmail.ch>
Date: Sun, 16 Oct 2022 22:56:08 +0300
Subject: [PATCH] Organize Doc Page (#90)

---
 docs/make.jl      |  3 +-
 docs/src/api.md   | 15 ++++++++
 docs/src/index.md | 92 ++++++++++++++++++++++++++++++++++++++++++-----
 3 files changed, 100 insertions(+), 10 deletions(-)
 create mode 100644 docs/src/api.md

diff --git a/docs/make.jl b/docs/make.jl
index b7c73e7..6cdacdd 100644
--- a/docs/make.jl
+++ b/docs/make.jl
@@ -7,7 +7,8 @@ makedocs(;
     modules=[ActuaryUtilities],
     format=Documenter.HTML(),
     pages=[
-        "Home" => "index.md",
+        "Introduction" => "index.md",
+        "API" => "api.md",
     ],
     repo="https://github.com/JuliaActuary/ActuaryUtilities.jl/blob/{commit}{path}#L{line}",
     sitename="ActuaryUtilities.jl",
diff --git a/docs/src/api.md b/docs/src/api.md
new file mode 100644
index 0000000..77ce551
--- /dev/null
+++ b/docs/src/api.md
@@ -0,0 +1,15 @@
+# ActuaryUtilities.jl
+
+```@index
+```
+
+```@meta
+DocTestSetup = quote
+    using ActuaryUtilities
+    using Dates
+end
+```
+
+```@autodocs
+Modules = [ActuaryUtilities]
+```
diff --git a/docs/src/index.md b/docs/src/index.md
index 77ce551..822a9d7 100644
--- a/docs/src/index.md
+++ b/docs/src/index.md
@@ -1,15 +1,89 @@
-# ActuaryUtilities.jl
+## Quickstart
 
-```@index
+```julia
+cfs = [5, 5, 105]
+times    = [1, 2, 3]
+discount_rate = 0.03
+present_value(discount_rate, cfs, times)           # 105.65
+duration(Macaulay(), discount_rate, cfs, times)    #   2.86
+duration(discount_rate, cfs, times)                #   2.78
+convexity(discount_rate, cfs, times)               #  10.62
 ```
 
-```@meta
-DocTestSetup = quote
-    using ActuaryUtilities
-    using Dates
-end
+## Features
+
+A collection of common functions/manipulations used in Actuarial Calculations.
+
+### Financial Maths
+
+- `duration`:
+  - Calculate the `Macaulay`, `Modified`, or `DV01` durations for a set of cashflows
+  - Calculate the `KeyRate(time)` (a.k.a. `KeyRateZero`)duration or `KeyRatePar(time)` duration
+- `convexity` for price sensitivity
+- Flexible interest rate options via the [`Yields.jl`](https://github.com/JuliaActuary/Yields.jl) package.
+- `internal_rate_of_return` or `irr` to calculate the IRR given cashflows (including at timepoints like Excel's `XIRR`)
+- `breakeven` to calculate the breakeven time for a set of cashflows
+- `accum_offset` to calculate accumulations like survivorship from a mortality vector
+- `spread` will calculate the spread needed between two yield curves to equate a set of cashflows
+
+### Options Pricing
+- `eurocall` and `europut` for Black-Scholes option prices (note: API may change for this in future)
+
+### Risk Measures
+
+- Calculate risk measures for a given vector of risks:
+  - `CTE` for the Conditional Tail Expectation, or
+  - `VaR` for the percentile/Value at Risk.
+
+### Insurance mechanics
+
+- `duration`:
+  - Calculate the duration given an issue date and date (a.k.a. policy duration)
+  
+
+### Typed Rates
+
+- functions which return a rate/yield will return a `Yields.Rate` object. E.g. `irr(cashflows)` will return a `Rate(0.05,Periodic(1))` instead of just a `0.05` (`float64`) to convey the compounding frequency. This uses (and is fully compatible with) Yields.jl and can be used anywhere you would otherwise use a simple floating point rate.
+
+A couple of other notes:
+
+- `rate(...)` will return the untyped rate from a `Yields.Rate` struct:
+
+```julia-repl
+julia> r = Yields.Rate(0.05,Yields.Periodic(1));
+julia> rate(r) 
+0.05
 ```
 
-```@autodocs
-Modules = [ActuaryUtilities]
+- You can still pass a simple floating point rate to various methods. E.g. these two are the same (the default compounding convention is periodic once per period):
+
+```julia
+discount(0.05,cashflows)
+r = Yields.Rate(0.05,Yields.Periodic(1));
+discount(r,cashflows)
+```
+
+- convert between rates with:
+
+```julia
+using Yields
+r = Yields.Rate(0.05,Yields.Periodic(1));
+convert(Yields.Periodic(2),  r)   # convert to compounded twice per timestep
+convert(Yields.Continuous(2),r)   # convert to compounded twice per timestep
 ```
+
+For more, see the [Yields.jl](https://github.com/JuliaActuary/Yields.jl) which provides a rich and flexible API for rates and curves to use.
+
+## Examples
+
+### Interactive, basic cashflow analysis
+
+See [JuliaActuary.org for instructions](https://juliaactuary.org/tutorials/cashflowanalysis/) on running this example.
+
+[![Simple cashflow analysis with ActuaryUtilities.jl](https://user-images.githubusercontent.com/711879/95857181-d646a280-0d20-11eb-8300-a4c226021334.gif)](https://juliaactuary.org/tutorials/cashflowanalysis/)
+
+
+
+## Useful tips
+
+Functions often use a mix of interest_rates, cashflows, and timepoints. When calling functions, the general order of the arguments is 1) interest rates, 2) cashflows, and 3) timepoints.