more doc cleanup

JuliaActuary · Oct 28, 2023 · 9414f24 · 9414f24
1 parent 1ac61c5
commit 9414f24
Show file tree

Hide file tree

Showing 19 changed files with 296 additions and 96 deletions.
diff --git a/docs/make.jl b/docs/make.jl
@@ -12,13 +12,26 @@ makedocs(;
         assets=String[]
     ),
     pages=[
-    # "Home" => "index.md",
-    # "Guide" => "guide.md",
-    # "Contracts" => "contracts.md",
-    # "Models, Valuation, and Fitting" => "models.md",
-    # "API Reference" => "api.md",
-    # "Migration Guide" => "migration.md",
-    # "FAQs" => "faq.md",
+        "Home" => "index.md",
+        "Guide" => [
+            "Introduction" => "introduction.md",
+            "Models, Valuation, and Fitting" => "models.md",
+            "Contracts" => "contracts.md",
+            "Rates" => "Rates.md",
+            "Migration Guide" => "migration.md",
+        ],
+        "Modules" => [
+            "FinanceModels" => "API/FinanceModels.md",
+            "FinanceCore" => "API/FinanceCore.md",
+            "Spline" => "API/Spline.md",
+            "Fit" => "API/Fit.md",
+            "Yield" => "API/Yield.md",
+            "Bond" => "API/Bond.md",
+            "Equity" => "API/Equity.md",
+            "Option" => "API/Option.md",
+            "Volatility" => "API/Volatility.md",
+        ],
+        "FAQs" => "faq.md",
     ],
     warnonly=true
 )

diff --git a/docs/src/API/Bond.md b/docs/src/API/Bond.md
@@ -0,0 +1,19 @@
+# FinanceModels.Bond API Reference
+
+```@index
+Modules = [FinanceModels.Bond]
+```
+
+## Exported API
+```@autodocs
+Modules = [FinanceModels.Bond]
+Private = false
+```
+
+## Unexported API
+```@autodocs
+Modules = [FinanceModels.Bond]
+Public = false
+```
+
+Please [open an issue](https://github.com/JuliaActuary/FinanceModels.jl/issues) if you encounter any issues or confusion with the package.
diff --git a/docs/src/API/Equity.md b/docs/src/API/Equity.md
@@ -0,0 +1,19 @@
+# FinanceModels.Equity API Reference
+
+```@index
+Modules = [FinanceModels.Equity]
+```
+
+## Exported API
+```@autodocs
+Modules = [FinanceModels.Equity]
+Private = false
+```
+
+## Unexported API
+```@autodocs
+Modules = [FinanceModels.Equity]
+Public = false
+```
+
+Please [open an issue](https://github.com/JuliaActuary/FinanceModels.jl/issues) if you encounter any issues or confusion with the package.
diff --git a/docs/src/API/FinanceCore.md b/docs/src/API/FinanceCore.md
@@ -0,0 +1,19 @@
+# FinanceCore API Reference
+
+```@index
+Modules = [FinanceCore]
+```
+
+## Exported API
+```@autodocs
+Modules = [FinanceCore]
+Private = false
+```
+
+## Unexported API
+```@autodocs
+Modules = [FinanceCore]
+Public = false
+```
+
+Please [open an issue](https://github.com/JuliaActuary/FinanceModels.jl/issues) if you encounter any issues or confusion with the package.
diff --git a/docs/src/API/FinanceModels.md b/docs/src/API/FinanceModels.md
@@ -0,0 +1,19 @@
+# FinanceModels API Reference
+
+```@index
+Modules = [FinanceModels]
+```
+
+## Exported API
+```@autodocs
+Modules = [FinanceModels]
+Private = false
+```
+
+## Unexported API
+```@autodocs
+Modules = [FinanceModels]
+Public = false
+```
+
+Please [open an issue](https://github.com/JuliaActuary/FinanceModels.jl/issues) if you encounter any issues or confusion with the package.
diff --git a/docs/src/API/Fit.md b/docs/src/API/Fit.md
@@ -0,0 +1,19 @@
+# FinanceModels.Fit API Reference
+
+```@index
+Modules = [FinanceModels.Fit]
+```
+
+## Exported API
+```@autodocs
+Modules = [FinanceModels.Fit]
+Private = false
+```
+
+## Unexported API
+```@autodocs
+Modules = [FinanceModels.Fit]
+Public = false
+```
+
+Please [open an issue](https://github.com/JuliaActuary/FinanceModels.jl/issues) if you encounter any issues or confusion with the package.
diff --git a/docs/src/API/Option.md b/docs/src/API/Option.md
@@ -0,0 +1,19 @@
+# FinanceModels.Option API Reference
+
+```@index
+Modules = [FinanceModels.Option]
+```
+
+## Exported API
+```@autodocs
+Modules = [FinanceModels.Option]
+Private = false
+```
+
+## Unexported API
+```@autodocs
+Modules = [FinanceModels.Option]
+Public = false
+```
+
+Please [open an issue](https://github.com/JuliaActuary/FinanceModels.jl/issues) if you encounter any issues or confusion with the package.
diff --git a/docs/src/API/Spline.md b/docs/src/API/Spline.md
@@ -0,0 +1,19 @@
+# FinanceModels.Spline API Reference
+
+```@index
+Modules = [FinanceModels.Spline]
+```
+
+## Exported API
+```@autodocs
+Modules = [FinanceModels.Spline]
+Private = false
+```
+
+## Unexported API
+```@autodocs
+Modules = [FinanceModels.Spline]
+Public = false
+```
+
+Please [open an issue](https://github.com/JuliaActuary/FinanceModels.jl/issues) if you encounter any issues or confusion with the package.
diff --git a/docs/src/API/Volatility.md b/docs/src/API/Volatility.md
@@ -0,0 +1,19 @@
+# FinanceModels.Volatility API Reference
+
+```@index
+Modules = [FinanceModels.Volatility]
+```
+
+## Exported API
+```@autodocs
+Modules = [FinanceModels.Volatility]
+Private = false
+```
+
+## Unexported API
+```@autodocs
+Modules = [FinanceModels.Volatility]
+Public = false
+```
+
+Please [open an issue](https://github.com/JuliaActuary/FinanceModels.jl/issues) if you encounter any issues or confusion with the package.
diff --git a/docs/src/API/Yield.md b/docs/src/API/Yield.md
@@ -0,0 +1,19 @@
+# FinanceModels.Yield API Reference
+
+```@index
+Modules = [FinanceModels.Yield]
+```
+
+## Exported API
+```@autodocs
+Modules = [FinanceModels.Yield]
+Private = false
+```
+
+## Unexported API
+```@autodocs
+Modules = [FinanceModels.Yield]
+Public = false
+```
+
+Please [open an issue](https://github.com/JuliaActuary/FinanceModels.jl/issues) if you encounter any issues or confusion with the package.
diff --git a/docs/src/Rates.md b/docs/src/Rates.md
@@ -0,0 +1,62 @@
+## Rates
+
+We should first discuss `Rate`s, which are reexported from [`FinanceCore.jl`](https://github.com/JuliaActuary/FinanceCore.jl)
+
+Rates are types that wrap scalar values to provide information about how to determine `discount` and `accumulation` factors. These allow for explicit handling of rate compounding conventions which, if not explicit, is often a source of errors in practice.
+
+There are two `Frequency` types:
+
+- `Yields.Periodic(m)` for rates that compound `m` times per period (e.g. `m` times per year if working with annual rates).
+- `Yields.Continuous()` for continuously compounding rates.
+
+#### Examples
+
+```julia
+Continuous(0.05)       # 5% continuously compounded
+Periodic(0.05,2)       # 5% compounded twice per period
+```
+
+These are both subtypes of the parent `Rate` type and are instantiated as:
+
+```julia
+Rate(0.05,Continuous())       # 5% continuously compounded
+Rate(0.05,Periodic(2))        # 5% compounded twice per period
+```
+
+Broadcast over a vector to create `Rates` with the given compounding:
+
+```julia
+Periodic.([0.02,0.03,0.04],2) 
+Continuous.([0.02,0.03,0.04]) 
+```
+
+Rates can also be constructed by specifying the `CompoundingFrequency` and then passing a scalar rate:
+
+```julia
+Periodic(1)(0.05)
+Continuous()(0.05)
+```
+
+#### Conversion
+
+Convert rates between different types with `convert`. E.g.:
+
+```julia
+r = Rate(0.01,Periodic(12))             # rate that compounds 12 times per rate period (ie monthly)
+
+convert(Yields.Periodic(1),r)                  # convert monthly rate to annual effective
+convert(Yields.Continuous(),r)          # convert monthly rate to continuous
+```
+
+To get the scalar value out of the `Rate`, use `FinanceModels.rate(r)`:
+
+```julia-rel
+julia> r = Rate(0.01,Periodic(12));   
+julia> rate(r)
+0.01
+
+```
+
+#### Arithmetic
+
+Adding, subtracting, multiplying, dividing, and comparing rates is supported.
diff --git a/docs/src/api.md b/docs/src/api.md
diff --git a/docs/src/contracts.md b/docs/src/contracts.md
@@ -1,13 +1,5 @@
 # Contracts
 
-## Page Contents
-
-```@contents
-Pages = ["contracts.md"]
-Depth = 4
-```
-
-
 ## **Contracts** - A composable way to represent financial instruments
 
 Contracts are a composable way to represent financial instruments. They are, in essence, anything that is a collection of cashflows. Contracts can be combined to represent more complex instruments. For example, a bond can be represented as a collection of cashflows that correspond to the coupon payments and the principal repayment.
@@ -96,22 +88,8 @@ Note that all contracts in FinanceModels.jl are currently *unit* contracts in th
 
 #### More complex Contracts
 
-**When the cashflow depends on a model**. An example of this is a floating bond where the coupon paid depends on a view of forward rates. See [this section in the overview](guide.html#Contracts-that-depend-on-the-model-(or-multiple-models)) on projections for how this is handled.
+**When the cashflow depends on a model**. An example of this is a floating bond where the coupon paid depends on a view of forward rates. See [this section in the overview](@ref Contracts-that-depend-on-the-model-(or-multiple-models)) on projections for how this is handled.
 
 ## Available Contracts & Modules
 
-### `Bond` Module
-
-```@autodocs; canonical=false
-Modules = [FinanceModels.Bond]
-```
-
-### Other Contracts
-
-- [Composite](@ref)
-- [CommonEquity](@ref)
-- [Forward](@ref)
-
-### Derivatives
-
-- [FinanceModels.Option](@ref)
+See the Modules in the left navigation for details on available contracts/models/functions.
diff --git a/docs/src/guide.md → docs/src/introduction.md b/docs/src/guide.md → docs/src/introduction.md
diff --git a/docs/src/migration.md b/docs/src/migration.md
@@ -37,7 +37,7 @@ quotes = ParYield.(rates,timepoints)
 model = fit(SmithWilson(),quotes)
 ```
 
-#### Discussion
+#### Details of changes
 
 Previously the kind of contract, the implied quotes, the type of model, and how the fitting process worked were all combined into a single call (`Yields.Par`). This minimized the amount of code needed to construct a yield curve, but left it fairly cumbersome to extend the package. For example, for every new yield curve model, methods for `Par`, `CMT`, `OIS`, `Zero`, ... had to be defined. Additionally, all of the inputs needed to be yields - specifying a price was not available as an argument to fit.