WIP docs update to strict docs build

JuliaActuary · Oct 28, 2023 · 1ac61c5 · 1ac61c5
1 parent 5b3630e
commit 1ac61c5
Show file tree

Hide file tree

Showing 14 changed files with 70 additions and 61 deletions.
diff --git a/docs/docs/Project.toml b/docs/docs/Project.toml
@@ -0,0 +1,4 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+FinanceCore = "b9b1ffdd-6612-4b69-8227-7663be06e089"
+FinanceModels = "77f2ae65-bdde-421f-ae9d-22f1af19dd76"
diff --git a/docs/make.jl b/docs/make.jl
@@ -2,7 +2,7 @@ using FinanceModels
 using Documenter
 
 makedocs(;
-    modules=[FinanceModels],
+    modules=[FinanceModels, FinanceCore],
     authors="Alec Loudenback <[email protected]> and contributors",
     repo="https://github.com/JuliaActuary/FinanceModels.jl/blob/{commit}{path}#L{line}",
     sitename="FinanceModels.jl",
@@ -12,14 +12,15 @@ 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" => "guide.md",
+    # "Contracts" => "contracts.md",
+    # "Models, Valuation, and Fitting" => "models.md",
+    # "API Reference" => "api.md",
+    # "Migration Guide" => "migration.md",
+    # "FAQs" => "faq.md",
+    ],
+    warnonly=true
 )
 
 deploydocs(;

diff --git a/docs/src/api.md b/docs/src/api.md
@@ -38,6 +38,14 @@ If you need to extract the rate for some reason, you can get the rate by calling
 ```@index
 ```
 
+## Exported API
 ```@autodocs
-Modules = [FinanceModels]
+Modules = [FinanceModels, FinanceCore, FinanceModels.Bond, FinanceModels.Yield, FinanceModels.Spline, FinanceModels.Fit, FinanceModels.Volatility,FinanceModels.Option, FinanceModels.Equity]
+Private = false
+```
+
+## Unexported API
+```@autodocs
+Modules = [FinanceModels, FinanceCore, FinanceModels.Bond, FinanceModels.Yield, FinanceModels.Spline, FinanceModels.Fit, FinanceModels.Volatility,FinanceModels.Option, FinanceModels.Equity]
+Public = false
 ```
diff --git a/docs/src/contracts.md b/docs/src/contracts.md
@@ -98,24 +98,20 @@ Note that all contracts in FinanceModels.jl are currently *unit* contracts in th
 
 **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.
 
-## Availalbe Contracts & Modules
+## Available Contracts & Modules
 
 ### `Bond` Module
 
-```@autodocs
+```@autodocs; canonical=false
 Modules = [FinanceModels.Bond]
 ```
 
 ### Other Contracts
 
-```@docs
-Composite
-CommonEquity
-Forward
-```
+- [Composite](@ref)
+- [CommonEquity](@ref)
+- [Forward](@ref)
 
 ### Derivatives
 
-```@autodocs
-Modules = [FinanceModels.Option]
-```
+- [FinanceModels.Option](@ref)
diff --git a/docs/src/faq.md b/docs/src/faq.md
@@ -19,10 +19,10 @@ Transducers are a [rich and powerful way to express programs](https://www.youtub
 - To regular end-users who just use what is given to them here, the transducers internals are effectively completely hidden
 - To moderately advanced users who want to extend the functionality, as the examples show the only real exposure here is a weird function name ( `__foldl__`) with for loop with a `return` signature that has some extra information.
 
-A number of examples of extending the package are given on the [Guide](./guide.html) page and the of course the source code itself offers examples of existing `Projection`s and `Contract`s.
+A number of examples of extending the package are given on the [FinanceModels.jl Guide](@ref) page and the of course the source code itself offers examples of existing `Projection`s and `Contract`s.
 
 
 ## I have another question
 
-Ask on the discussion forum here: https://github.com/JuliaActuary/Yields.jl/discussions
+Ask on the discussion forum here: [https://github.com/JuliaActuary/FinanceModels.jl/discussions](https://github.com/JuliaActuary/FinanceModels.jl/discussions)
 
diff --git a/docs/src/guide.md b/docs/src/guide.md
@@ -2,7 +2,7 @@
 
 **FinanceModels.jl** provides a set of composable contracts, models, and functions that allow for modeling of both simple and complex financial instruments. The resulting models, such as discount rates or term structures, can then be used across the JuliaActuary ecosystem to perform actuarial and financial analysis.
 
-![A conceptual sketch of FinanceModels.jl](./assets/relations.png)
+![A conceptual sketch of FinanceModels.jl](assets/relations.png)
 
 ## 1. `Cashflow` - a fundamental financial type
 
@@ -332,7 +332,7 @@ julia> p = Projection(
 ```
 
 And then collect the values:
-[](url)
+
 ```julia-repl
 julia> collect(p)
 10-element Vector{NamedTuple{(:time, :payment, :outstanding), Tuple{Float64, Float64, Float64}}}:

diff --git a/docs/src/index.md b/docs/src/index.md
@@ -43,7 +43,7 @@ present_value(m_rate,Cashflow(10,3)) # 9.15...
 ## Overview of FinanceModels
 
 
-![A conceptual sketch of FinanceModels.jl](/docs/src/assets/relations.png)
+![A conceptual sketch of FinanceModels.jl](assets/relations.png)
 
 Often we start with observed or assumed values for existing contracts. We want to then use those assumed values to extend the valuation logic to new contracts. For example, we may have a set of bond yields which we then want to discount a series of insurance obligations.
 

diff --git a/docs/src/models.md b/docs/src/models.md
@@ -74,11 +74,11 @@ Adding, subtracting, multiplying, dividing, and comparing rates is supported.
 
 ### Available Models - Yields
 
-- [`Yield.Constant`](@ref)
-- Bootstrapped [`Spline`](@ref)
-- [`Yield.SmithWilson`](@ref)
-- [`Yield.NelsonSiegel`](@ref)
-- [`Yield.NelsonSiegelSvensson`](@ref)
+- [`FinanceModels.Yield.Constant`](@ref)
+- Bootstrapped [`Spline`](@ref FinanceModels.Spline)s
+- [`FinanceModels.Yield.SmithWilson`](@ref)
+- [`FinanceModels.Yield.NelsonSiegel`](@ref)
+- [`FinanceModels.Yield.NelsonSiegelSvensson`](@ref)
 
 Yield models can also be composed. Here is an example of fitting rates and spread separately and then adding the two models together:
 
@@ -106,20 +106,20 @@ julia> discount(0.04,3)
 
 ### Creating New Yield Models
 
-See the [Guide](guide.html) for an example of creating a model from scratch. Some additional aspects to note:
+See the [FinanceModels.jl Guide](@ref) for an example of creating a model from scratch. Some additional aspects to note:
 
-- The only method that must be defined to calculate the [`present_value`](@ref) of something is [`discount`](@ref). Other methods will be inferred.
-- Other methods that are imputed by default, but can be extended include: [`accumulation`](@ref), [`forward`](@ref), [`par`](@ref), [`zero`](@ref), and [`rate`](@ref).
+- The only method that must be defined to calculate the [`FinanceCore.present_value`](@ref) of something is [`FinanceCore.discount`](@ref). Other methods will be inferred.
+- Other methods that are imputed by default, but can be extended include: [`FinanceCore.accumulation`](@ref), [`FinanceModels.forward`](@ref), [`FinanceModels.par`](@ref), [`FinanceModels.zero`](@ref), and [`FinanceModels.rate`](@ref).
 
 ## Equity and Volatility Models
 
 ### Available Models - Option Valuation
 
-- [`Option.BlackScholesMerton`](@ref)
+- [`FinanceModels.Option.BlackScholesMerton`](@ref)
 
 ### Available Models - Volatility
 
-- [`Volatility.Constant`](@ref)
+- [`FinanceModels.Volatility.Constant`](@ref)
 
 #### Creating new Volatility Models
 

diff --git a/src/Contract.jl b/src/Contract.jl
@@ -92,7 +92,7 @@ Note that there are a number of convienience constructors which return a Quote f
 - [`CMTYield`](@ref)
 - [`OISYield`](@ref)
 
-See also [`Quote`](@ref).
+See also [`FinanceCore.Quote`](@ref).
 
 # Examples
 
@@ -131,7 +131,7 @@ end
 An object representing a floating coupon bond. (`coupon_rate` + reference rate) / `frequency` is the actual payment amount, where the reference rate requires a `Projection` with a key/value pair where the key is the `model_key` argument and the value is the model which produces the reference rate.
 
 
-See also [`Quote`](@ref).
+See also [`FinanceCore.Quote`](@ref).
 
 # Examples
 
@@ -206,7 +206,7 @@ Returns a `Quote` for the correpsonding bond implied by the given bond equivalen
 
 Use broadcasting to create a set of quotes given a collection of FinanceModels and maturities, e.g. `CMTYield.(FinanceModels,maturities)`.
 
-See also [`Quote`](@ref), [`Bond.Fixed`](@ref)
+See also [`FinanceCore.Quote`](@ref), [`Bond.Fixed`](@ref)
 
 # Examples
 
@@ -235,7 +235,7 @@ Returns the implied `Quote` for the fixed bond implied by the given `yield` and
 
 Use broadcasting to create a set of quotes given a collection of FinanceModels and maturities, e.g. `OISYield.(FinanceModels,maturities)`.
 
-See also [`Quote`](@ref), [`Bond.Fixed`](@ref)
+See also [`FinanceCore.Quote`](@ref), [`Bond.Fixed`](@ref)
 
 # Examples
 

diff --git a/src/fit.jl b/src/fit.jl
@@ -48,7 +48,7 @@ end
 """
     Bootstrap()
 
-A singleton type which is passed to `fit` in order to bootstrap [`Spline`](@ref)s. The curves are fit such that the spline passes through the zero rates of the curve. 
+A singleton type which is passed to `fit` in order to bootstrap [`Spline`](@ref FinanceModels.Spline)s. The curves are fit such that the spline passes through the zero rates of the curve. 
 
 A subtype of FitMethod.
 
@@ -153,24 +153,24 @@ __default_optim(m) = ECA()
 
 """
     fit(
-        mod0, 
+        model, 
         quotes, 
         method=Fit.Loss(x -> x^2);
-        variables=__default_optic(mod0), 
-        optimizer=__default_optim(mod0)
+        variables=__default_optic(model), 
+        optimizer=__default_optim(model)
         )
 
 Fit a model to a collection of quotes using a loss function and optimization method.
 
 ## Arguments
-- `mod0`: The initial model to fit, which is generally an instantiated but un-optimized model.
+- `model`: The initial model to fit, which is generally an instantiated but un-optimized model.
 - `quotes`: A collection of quotes to fit the model to.
 - `method::F=Fit.Loss(x -> x^2)`: The loss function to use for fitting the model. Defaults to the squared loss function. 
-  - `method` can also be `Bootstrap()`. If this is the case, `mod0` should be a spline such as `Spline.Linear()`, `Spline.Cubic()`...
-- `variables=__default_optic(mod0)`: The variables to optimize over. This is an optic specifying which parameters of the modle can vary. See extended help for more.
-- `optimizer=__default_optim(mod0)`: The optimization algorithm to use. The default optimization for a given model is ECA from Metahueristics.jl; see extended help for more on customizing the solver including setting the seed.
+  - `method` can also be `Bootstrap()`. If this is the case, `model` should be a spline such as `Spline.Linear()`, `Spline.Cubic()`...
+- `variables=__default_optic(model)`: The variables to optimize over. This is an optic specifying which parameters of the modle can vary. See extended help for more.
+- `optimizer=__default_optim(model)`: The optimization algorithm to use. The default optimization for a given model is ECA from Metahueristics.jl; see extended help for more on customizing the solver including setting the seed.
 
-The optimization routine will then attempt to modify parameters of `mod0` to best fit the quoted prices of the contracts underlying the `quotes` by calling `present_value(model,contract)`. The optimization will minimize the loss function specified within `Fit.Loss(...)`. 
+The optimization routine will then attempt to modify parameters of `model` to best fit the quoted prices of the contracts underlying the `quotes` by calling `present_value(model,contract)`. The optimization will minimize the loss function specified within `Fit.Loss(...)`. 
 
 Different types of quotes are appropriate for different kinds of models. For example, if you try to value a set of equtiy `EuroCall`s with a `Yield.Constant`, you will get an error because the `present_value(m<:Yield.Constant,o<:EuroCall)` is not defined.
 
@@ -179,11 +179,11 @@ Different types of quotes are appropriate for different kinds of models. For exa
 
 # Examples
 ```julia
-julia> mod0 = Yield.Constant();
+julia> model = Yield.Constant();
 
 julia> quotes = ZCBPrice([0.9, 0.8, 0.7,0.6]);
 
-julia> fit(mod0,quotes)
+julia> fit(model,quotes)
 
               ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀Yield Curve (FinanceModels.Yield.Constant)⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀           
               ┌────────────────────────────────────────────────────────────┐           

diff --git a/src/model/Equity.jl b/src/model/Equity.jl
@@ -23,7 +23,7 @@ A struct representing the Black-Scholes-Merton model for equity prices.
 - `q`: The dividend yield.
 - `σ`: The volatility model of the underlying asset (see [`Volatility`](@ref) module)
 
-When [`fit`](@ref), the volatility will be solved-for; volatility itself is a sub-model that will be optimized with a default optimization bound of `0.0 .. 10.0`
+When [`fit`](@ref FinanceModels.fit-Union{Tuple{F}, Tuple{Any, Any}, Tuple{Any, Any, F}} where F<:FinanceModels.Fit.Loss)ting, the volatility will be solved-for; volatility itself is a sub-model that will be optimized with a default optimization bound of `0.0 .. 10.0`
 
 # Examples
 ```julia-repl

diff --git a/src/model/Spline.jl b/src/model/Spline.jl
@@ -1,11 +1,11 @@
 """
-Spline is a module which offers various degree splines used for fitting or bootstraping curves via the [`fit`](@ref) function.
+Spline is a module which offers various degree splines used for fitting or bootstraping curves via the [`fit`](@ref FinanceModels.fit-Union{Tuple{F}, Tuple{Any, Any}, Tuple{Any, Any, F}} where F<:FinanceModels.Fit.Loss) function.
 
 Available methods:
 
 - `Spline.BSpline(n)` where n is the nth order. A spline function of order n is a piecewise polynomial function of degree n − 1. This means that, e.g., cubic polynomial is a fourth degree B-Spline.
 
-This object is not a fitted spline itself, rather it is a placeholder object which will be a spline representing the data only after using within [`fit`](@ref).
+This object is not a fitted spline itself, rather it is a placeholder object which will be a spline representing the data only after using within [`fit`](@ref FinanceModels.fit-Union{Tuple{F}, Tuple{Any, Any}, Tuple{Any, Any, F}} where F<:FinanceModels.Fit.Loss).
 
 and convienience methods which create a `Spline.BSpline` object of the appropriate order.
 
@@ -26,7 +26,7 @@ end
 """
     Spline.Linear()
 
-Create a linear B-spline. This object is not a fitted spline itself, rather it is a placeholder object which will be a spline representing the data only after using within [`fit`](@ref).
+Create a linear B-spline. This object is not a fitted spline itself, rather it is a placeholder object which will be a spline representing the data only after using within [`fit`](@ref FinanceModels.fit-Union{Tuple{F}, Tuple{Any, Any}, Tuple{Any, Any, F}} where F<:FinanceModels.Fit.Loss).
 
 # Returns
 - A `BSpline` object representing a linear B-spline.
@@ -44,7 +44,7 @@ Linear() = BSpline(2)
 """
     Spline.Quadratic()
 
-Create a quadratic B-spline. This object is not a fitted spline itself, rather it is a placeholder object which will be a spline representing the data only after using within [`fit`](@ref).
+Create a quadratic B-spline. This object is not a fitted spline itself, rather it is a placeholder object which will be a spline representing the data only after using within [`fit`](@ref FinanceModels.fit-Union{Tuple{F}, Tuple{Any, Any}, Tuple{Any, Any, F}} where F<:FinanceModels.Fit.Loss).
 
 # Returns
 - A `BSpline` object representing a quadratic B-spline.
@@ -60,7 +60,7 @@ Quadratic() = BSpline(3)
 """
     Spline.Cubic()
 
-Create a cubic B-spline. This object is not a fitted spline itself, rather it is a placeholder object which will be a spline representing the data only after using within [`fit`](@ref).
+Create a cubic B-spline. This object is not a fitted spline itself, rather it is a placeholder object which will be a spline representing the data only after using within [`fit`](@ref FinanceModels.fit-Union{Tuple{F}, Tuple{Any, Any}, Tuple{Any, Any, F}} where F<:FinanceModels.Fit.Loss).
 
 # Returns
 - A `BSpline` object representing a cubic B-spline.

diff --git a/src/model/Yield.jl b/src/model/Yield.jl
@@ -1,4 +1,3 @@
-
 module Yield
 import ..AbstractModel
 import ..FinanceCore
@@ -16,9 +15,10 @@ abstract type AbstractYieldModel <: AbstractModel end
 """
     Constant(rate)
 
-A yield curve representing a flat term structure. 
+A yield curve representing a flat term structure. `rate` can be a [`Rate`](@ref) object or a `Real` object.
+
 
-The solver will attempt to fit a discount rate with the range of: `-1.0 .. 1.0`
+If [`fit`](@ref FinanceModels.fit-Union{Tuple{F}, Tuple{Any, Any}, Tuple{Any, Any, F}} where F<:FinanceModels.Fit.Loss)ing with the default FinanceModels.jl settings, the solver will attempt to fit a discount rate with the range of: `-1.0 .. 1.0`
 """
 struct Constant{R} <: AbstractYieldModel
     rate::R
@@ -200,7 +200,7 @@ julia> FinanceCore.discount(fwd,1) # `curve` has effectively been reindexed to `
 
 While `ForwardStarting` could be nested so that, e.g. the third period's curve is the one-period forward of the second period's curve, it will be more efficient to reuse the initial curve from a runtime and compiler perspective.
 
-`ForwardStarting` is not used to construct a curve based on forward rates. See  [`Forward`](@ref) instead.
+`ForwardStarting` is not used to construct a curve based on forward rates. 
 """
 struct ForwardStarting{T,U} <: AbstractYieldModel
     curve::U

diff --git a/src/model/Yield/SmithWilson.jl b/src/model/Yield/SmithWilson.jl
@@ -12,7 +12,7 @@ using ..FinanceCore
     
 Create a yield curve object that implements the Smith-Wilson interpolation/extrapolation scheme.
 
-To calibrate a curve, you generally want to construct the object without the `u` and `qb` arguments and call [`fit`](@ref) in conjunction with Quotes (`fit` requires no third parameter for SmithWilson curves). See **Examples** for what this looks like. 
+To calibrate a curve, you generally want to construct the object without the `u` and `qb` arguments and call [`fit`](@ref FinanceModels.fit-Union{Tuple{F}, Tuple{Any, Any}, Tuple{Any, Any, F}} where F<:FinanceModels.Fit.Loss) in conjunction with Quotes (`fit` requires no third parameter for SmithWilson curves). See **Examples** for what this looks like. 
 Positional arguments to construct a curve:
 - A curve can be with `u` is the timepoints coming from the calibration, and `qb` is the internal parameterization of the curve that ensures that the calibration is correct. Users may prefer the other constructors but this mathematical constructor is also available.