Merge pull request #2 from quant-sci/update-docs

feat: enhance the documentation and change for furo template

Author: Kleyt0n

.readthedocs.yaml

@@ -1,23 +1,16 @@
 # Read the Docs configuration file
 # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
 
-# Required
 version: 2
 
-# Set the OS, Python version, and other tools you might need
 build:
   os: ubuntu-24.04
   tools:
     python: "3.13"
 
-# Build documentation in the "docs/" directory with Sphinx
 sphinx:
    configuration: docs/conf.py
 
-# Optionally, but recommended,
-# declare the Python requirements required to build your documentation
-# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
-# python:
-#    install:
-#    - requirements: docs/requirements.txt
-        
+python:
+  install:
+    - requirements: docs/requirements.txt

README.md

@@ -11,30 +11,31 @@
 ## Installation
 
 ```bash
+pip install dynaris
+# or
 uv add dynaris
 ```
 
+## Documentation
+
+Full documentation is available at [dynaris.readthedocs.io](https://dynaris.readthedocs.io).
+
 ## Quickstart
 
 ```python
-from dynaris import LocalLevel, Seasonal, DLM
+from dynaris import LocalLevel, DLM
 from dynaris.datasets import load_nile
 
 # Load data
 y = load_nile()
 
-# Build a model by composing components
-model = LocalLevel(sigma_level=38.0, sigma_obs=123.0) + Seasonal(period=12)
-
-# Fit, smooth, forecast
-dlm = DLM(model)
+# Build a local-level model and fit
+dlm = DLM(LocalLevel(sigma_level=38.0, sigma_obs=123.0))
 dlm.fit(y).smooth()
-fc = dlm.forecast(steps=12)
 
-# Print summary
+# Forecast and plot
+fc = dlm.forecast(steps=10)
 print(dlm.summary())
-
-# Single-figure overview
 dlm.plot(kind="panel")
 ```
 
@@ -43,7 +44,7 @@ dlm.plot(kind="panel")
 Build models by combining components with `+`:
 
 ```python
-from dynaris import LocalLinearTrend, Seasonal, Cycle, Autoregressive, Regression
+from dynaris import LocalLinearTrend, Seasonal, Cycle
 
 model = (
     LocalLinearTrend(sigma_level=1.0, sigma_slope=0.1)
@@ -80,26 +81,14 @@ print(f"Log-likelihood: {result.log_likelihood:.2f}")
 
 ## Datasets
 
-```python
-from dynaris.datasets import load_nile, load_airline, load_lynx, load_sunspots, load_temperature, load_gdp
-
-y = load_airline()     # 144 monthly obs, 1949-1960
-y = load_lynx()        # 114 annual obs, 1821-1934 (~10-year cycle)
-y = load_sunspots()    # 288 annual obs, 1700-1987 (~11-year cycle)
-y = load_temperature() # 144 annual obs, 1880-2023 (warming trend)
-y = load_gdp()         # 319 quarterly obs, 1947-2026 (business cycle)
-```
-
-## Notation
-
-Dynaris follows the West & Harrison (1997) notation:
-
-| Symbol | Code | Meaning |
-|--------|------|---------|
-| **G** | `model.G` / `system_matrix` | System (evolution) matrix |
-| **F** | `model.F` / `observation_matrix` | Observation (regression) matrix |
-| **W** | `model.W` / `evolution_cov` | Evolution covariance |
-| **V** | `model.V` / `obs_cov` | Observational variance |
+| Dataset | Loader | N | Frequency | Domain |
+|---------|--------|---|-----------|--------|
+| Nile river flow | `load_nile()` | 100 | Annual | Hydrology |
+| Airline passengers | `load_airline()` | 144 | Monthly | Transportation |
+| Lynx population | `load_lynx()` | 114 | Annual | Ecology |
+| Sunspot numbers | `load_sunspots()` | 288 | Annual | Astronomy |
+| Global temperature | `load_temperature()` | 144 | Annual | Climate |
+| US GDP growth | `load_gdp()` | 319 | Quarterly | Economics |
 
 ## License
 

docs/_static/custom.css

@@ -0,0 +1,3 @@
+.sidebar-logo img {
+    max-width: 80px;
+}

docs/_static/logo.png

@@ -3,16 +3,25 @@ DLM Components
 
 Composable building blocks for Dynamic Linear Models. Each function returns
 a :class:`~dynaris.core.state_space.StateSpaceModel` that can be composed
-via the ``+`` operator.
+via the ``+`` operator. See :doc:`/user-guide/components` for usage guidance.
+
+Trend
+-----
 
 .. autofunction:: dynaris.dlm.components.LocalLevel
 
 .. autofunction:: dynaris.dlm.components.LocalLinearTrend
 
+Periodic
+--------
+
 .. autofunction:: dynaris.dlm.components.Seasonal
 
+.. autofunction:: dynaris.dlm.components.Cycle
+
+Other
+-----
+
 .. autofunction:: dynaris.dlm.components.Regression
 
 .. autofunction:: dynaris.dlm.components.Autoregressive
-
-.. autofunction:: dynaris.dlm.components.Cycle

docs/api/components.rst

@@ -1,40 +1,58 @@
 Core Types
 ==========
 
-Fundamental data structures: state-space model, Gaussian state, result
-containers, and filter/smoother protocols.
+Fundamental data structures used throughout dynaris. These are the building
+blocks that filters, smoothers, and the DLM class operate on.
 
 StateSpaceModel
 ---------------
 
+The central model representation. Holds the four system matrices (F, G, V, W)
+following West and Harrison (1997) notation. Returned by all component
+functions and composed via ``+``.
+
 .. autoclass:: dynaris.core.state_space.StateSpaceModel
    :members:
    :show-inheritance:
 
 GaussianState
 -------------
 
+Represents a Gaussian belief about the state: a mean vector and covariance
+matrix. Used internally by the Kalman filter and smoother at each time step.
+
 .. autoclass:: dynaris.core.types.GaussianState
    :members:
    :show-inheritance:
 
 FilterResult
 ------------
 
+Container returned by the Kalman filter. Holds filtered state means,
+covariances, log-likelihood, and forecast errors for all time steps.
+
 .. autoclass:: dynaris.core.results.FilterResult
    :members:
    :show-inheritance:
+   :no-index:
 
 SmootherResult
 --------------
 
+Container returned by the RTS smoother. Holds smoothed state means and
+covariances for all time steps.
+
 .. autoclass:: dynaris.core.results.SmootherResult
    :members:
    :show-inheritance:
+   :no-index:
 
 Protocols
 ---------
 
+Interfaces that filter and smoother implementations must satisfy. Useful
+for type checking and extending dynaris with custom algorithms.
+
 .. autoclass:: dynaris.core.protocols.FilterProtocol
    :members:
 

docs/api/core.rst

@@ -0,0 +1,18 @@
+Datasets
+========
+
+Built-in dataset loaders for examples and testing. Each function returns a
+pandas ``Series`` with an appropriate index. See :doc:`/user-guide/datasets`
+for a summary table.
+
+.. autofunction:: dynaris.datasets.data.load_nile
+
+.. autofunction:: dynaris.datasets.data.load_airline
+
+.. autofunction:: dynaris.datasets.data.load_lynx
+
+.. autofunction:: dynaris.datasets.data.load_sunspots
+
+.. autofunction:: dynaris.datasets.data.load_temperature
+
+.. autofunction:: dynaris.datasets.data.load_gdp

docs/api/datasets.rst

@@ -3,7 +3,16 @@ DLM --- High-Level Interface
 
 The :class:`~dynaris.dlm.api.DLM` class is the primary user-facing interface.
 It wraps a :class:`~dynaris.core.state_space.StateSpaceModel` with convenient
-``fit``, ``forecast``, ``smooth``, ``plot``, and ``summary`` methods.
+methods for the full modeling workflow:
+
+1. ``fit(y)`` --- run the Kalman filter
+2. ``smooth()`` --- run the RTS smoother
+3. ``forecast(steps)`` --- multi-step-ahead predictions
+4. ``plot(kind)`` --- visualize results
+5. ``summary()`` --- print model and fit information
+
+Most users only need this class. The lower-level filter, smoother, and
+forecast functions are available for advanced use cases.
 
 .. autoclass:: dynaris.dlm.api.DLM
    :members:

docs/api/dlm.rst

@@ -1,11 +1,17 @@
 Parameter Estimation
 ====================
 
-Maximum likelihood estimation, EM algorithm, and model diagnostics.
+Maximum likelihood estimation, EM algorithm, residual diagnostics, and
+parameter transforms. See :doc:`/user-guide/estimation` for a guide on
+choosing between MLE and EM.
 
 MLE
 ---
 
+Gradient-based optimization of the log-likelihood using JAX autodiff.
+Flexible: supports any differentiable parameterization via a user-defined
+``model_fn``.
+
 .. autofunction:: dynaris.estimation.mle.fit_mle
 
 .. autoclass:: dynaris.estimation.mle.MLEResult
@@ -14,6 +20,9 @@ MLE
 EM Algorithm
 ------------
 
+Iterative variance estimation with guaranteed non-decreasing log-likelihood.
+Simpler setup than MLE --- just pass an initial model.
+
 .. autofunction:: dynaris.estimation.em.fit_em
 
 .. autoclass:: dynaris.estimation.em.EMResult
@@ -22,6 +31,8 @@ EM Algorithm
 Diagnostics
 -----------
 
+Tools for checking model adequacy after fitting.
+
 .. autofunction:: dynaris.estimation.diagnostics.standardized_residuals
 
 .. autofunction:: dynaris.estimation.diagnostics.acf
@@ -33,6 +44,8 @@ Diagnostics
 Transforms
 ----------
 
+Map unconstrained parameters to positive values for variance estimation.
+
 .. autofunction:: dynaris.estimation.transforms.softplus
 
 .. autofunction:: dynaris.estimation.transforms.inverse_softplus

docs/api/estimation.rst

@@ -1,7 +1,16 @@
 Kalman Filter
 =============
 
-Forward filtering for linear-Gaussian state-space models.
+Forward filtering for linear-Gaussian state-space models. The Kalman filter
+processes observations sequentially, computing the posterior state distribution
+at each time step.
+
+.. note::
+
+   Most users do not need to call these functions directly ---
+   :meth:`DLM.fit() <dynaris.dlm.api.DLM.fit>` wraps the Kalman filter
+   internally. These are available for advanced use cases requiring direct
+   access to intermediate filter quantities.
 
 .. autoclass:: dynaris.filters.kalman.KalmanFilter
    :members: