Add more docs

Add docstrings for cash function/class

Fix doc link

fix type

Fix formatting for CI

Author: jathoms

docs/source/reference/decision/index.rst

@@ -0,0 +1,30 @@
+========
+Decision
+========
+
+.. currentmodule:: backtest_lib
+
+Decision Type
+-------------
+
+.. currentmodule:: backtest_lib.engine.decision
+
+.. autosummary::
+   :toctree: api/
+
+   Decision
+
+Decision Functions
+------------------
+
+.. currentmodule:: backtest_lib
+
+.. autosummary::
+   :toctree: api/
+
+   hold
+   target_holdings
+   target_weights
+   trade
+   reallocate
+   combine

docs/source/reference/engine/decision/index.rst

@@ -1,25 +1,20 @@
-Decision
-========
+Decision Types
+==============
 
 .. currentmodule:: backtest_lib.engine.decision
 
-Decision Constructors
----------------------
+Decision Objects
+----------------
 
 .. autosummary::
    :toctree: api/
 
-   hold
-   target_holdings
-   target_weights
-   trade
-   reallocate
-   combine
-
-Decision Type
--------------
-
-.. autosummary::
-   :toctree: api/
-
-   Decision
+   DecisionBase
+   CompositeDecision
+   HoldDecision
+   MakeTradeDecision
+   ReallocateDecision
+   TargetHoldingsDecision
+   TargetWeightsDecision
+   ReallocationMode
+   TradeDirection

docs/source/reference/index.rst

@@ -8,6 +8,7 @@ This is an overview of the public API of backtest-lib.
   :hidden:
 
   backtest/index
+  decision/index
   market/index
   strategy/index
   portfolio/index

src/backtest_lib/backtest/results.py

@@ -23,8 +23,7 @@
 
 @dataclass
 class BacktestResults[IndexT: Comparable]:
-    """Snapshot of a backtest's results, with key statistics pre-computed.
-    """
+    """Snapshot of a backtest's results, with key statistics pre-computed."""
 
     periods: Sequence[IndexT] = field(repr=False)
     securities: Sequence[str] = field(repr=False)

src/backtest_lib/engine/decision/__init__.py

@@ -9,7 +9,13 @@
 
 
 class ReallocationMode(StrEnum):
-    """Modes for allocating out of and into security sets."""
+    """Modes for allocating out of and into security sets.
+
+    - ``EQUAL_OUT_EQUAL_IN`` sells evenly across ``out_of`` and buys evenly into
+      ``into``.
+    - ``PRO_RATA_OUT_EQUAL_IN`` sells in proportion to existing weights and buys
+      evenly into ``into``.
+    """
 
     EQUAL_OUT_EQUAL_IN = "equal_out_equal_in"
     PRO_RATA_OUT_EQUAL_IN = "pro_rata_out_equal_in"
@@ -30,8 +36,13 @@ class DecisionBase:
     form composite decisions.
     """
 
-    def __add__(self, other: Decision) -> Decision:
-        """Combine two decisions into a composite decision."""
+    def __add__(self: Decision, other: Decision) -> Decision:
+        """Combine two decisions into a composite decision.
+
+        ``HoldDecision`` acts as the identity element. When either side is a
+        :class:`HoldDecision`, the other decision is returned. Two composites are
+        flattened into a single :class:`CompositeDecision`.
+        """
         if isinstance(self, HoldDecision):
             return other
         if isinstance(other, HoldDecision):
@@ -43,7 +54,10 @@ def __add__(self, other: Decision) -> Decision:
 
 @dataclass(frozen=True, slots=True)
 class MakeTradeDecision(DecisionBase):
-    """Decision returned by :func:`~backtest_lib.engine.decision.trade`."""
+    """Decision representing an explicit buy or sell instruction.
+
+    Use :func:`~backtest_lib.engine.decision.trade` to construct this decision.
+    """
 
     direction: TradeDirection
     qty: int
@@ -57,14 +71,22 @@ def __post_init__(self):
 
 @dataclass(frozen=True, slots=True)
 class CompositeDecision(DecisionBase):
-    """Decision returned by :func:`~backtest_lib.engine.decision.combine`."""
+    """Decision containing multiple sub-decisions.
+
+    Use :func:`~backtest_lib.engine.decision.combine` to construct this decision
+    or rely on ``+`` to merge decisions.
+    """
 
     decisions: tuple[Decision, ...]
 
 
 @dataclass(frozen=True, slots=True)
 class TargetHoldingsDecision(DecisionBase):
-    """Decision returned by :func:`~backtest_lib.engine.decision.target_holdings`."""
+    """Decision targeting discrete share counts for each security.
+
+    Use :func:`~backtest_lib.engine.decision.target_holdings` to construct this
+    decision.
+    """
 
     target_holdings: Mapping[str, int]
     fill_cash: bool
@@ -73,7 +95,11 @@ class TargetHoldingsDecision(DecisionBase):
 
 @dataclass(frozen=True, slots=True)
 class TargetWeightsDecision(DecisionBase):
-    """Decision returned by :func:`~backtest_lib.engine.decision.target_weights`."""
+    """Decision targeting portfolio weights for each security.
+
+    Use :func:`~backtest_lib.engine.decision.target_weights` to construct this
+    decision.
+    """
 
     target_weights: Mapping[str, float]
     fill_cash: bool
@@ -82,14 +108,21 @@ class TargetWeightsDecision(DecisionBase):
 
 @dataclass(frozen=True, slots=True)
 class HoldDecision(DecisionBase):
-    """Decision returned by :func:`~backtest_lib.engine.decision.hold`."""
+    """Decision that leaves the portfolio unchanged.
+
+    Use :func:`~backtest_lib.engine.decision.hold` to construct this decision.
+    """
 
     pass
 
 
 @dataclass(frozen=True, slots=True)
 class ReallocateDecision(DecisionBase):
-    """Decision returned by :func:`~backtest_lib.engine.decision.reallocate`."""
+    """Decision to move exposure from one security set to another.
+
+    Use :func:`~backtest_lib.engine.decision.reallocate` to construct this
+    decision.
+    """
 
     fraction: float
     from_securities: frozenset[str]
@@ -115,7 +148,9 @@ def reallocate(
         fraction: Fraction of holdings to reallocate.
         out_of: Securities to reduce positions in.
         into: Securities to increase positions in.
-        mode: Allocation mode for distributing sales and buys.
+        mode: Allocation mode for distributing sales and buys. Accepts
+            ``"equal_out_equal_in"``, ``"pro_rata_out_equal_in"``, or a
+            :class:`~backtest_lib.engine.decision.ReallocationMode`.
 
     Returns:
         ReallocateDecision describing the move.
@@ -153,8 +188,7 @@ def hold() -> HoldDecision:
     """Create a decision that makes no trades.
 
     This is the neutral element of the decision language. When combined with
-    another decision, the other decision is returned unchanged, mirroring
-    :func:`~backtest_lib.engine.decision.combine`.
+    another decision, the other decision is returned unchanged.
     """
     return HoldDecision()
 
@@ -165,7 +199,8 @@ def target_holdings(
     """Create a decision targeting discrete holdings.
 
     This is part of the strategy output language. Use it when your strategy
-    expresses desired positions as share counts.
+    expresses desired positions as share counts. The holdings keys must be a
+    subset of the strategy universe; missing securities are treated as zero.
 
     Args:
         holdings: Desired integer holdings per security.
@@ -184,7 +219,9 @@ def target_weights(
     """Create a decision targeting portfolio weights.
 
     This is part of the strategy output language. Use it when your strategy
-    expresses desired positions as weights that should sum with cash.
+    expresses desired positions as weights that should sum with cash. The weight
+    keys must be a subset of the strategy universe; missing securities are
+    treated as zero.
 
     Args:
         weights: Desired weights per security.
@@ -220,10 +257,11 @@ def trade(
 
     This is part of the strategy output language for explicit trades. Use it
     when you want a single-buy/sell instruction rather than a target portfolio
-    expressed via :func:`~backtest_lib.engine.decision.target_weights`.
+    expressed via :func:`~backtest_lib.target_weights`.
 
     Args:
-        direction: Buy or sell direction.
+        direction: Buy or sell direction. Accepts ``"buy"``, ``"sell"``, or a
+            :class:`~backtest_lib.engine.decision.TradeDirection`.
         qty: Quantity to trade.
         security: Security identifier to trade.
 

src/backtest_lib/engine/execute/perfect_world.py

@@ -354,9 +354,9 @@ def execute_plan(
         prices: UniverseMapping,
         market: MarketView,
     ) -> ExecutionResult:
-        """Executes a plan with assumptions of perfect conditions i.e no fees or slippage.
-        Any targetting op will instantly change the portfolio to that target, so the
-        convention in ``self._normalize_ops`` is to yield the target first.
+        """Executes a plan with assumptions of perfect conditions i.e no fees or
+        slippage. Any targetting op will instantly change the portfolio to that target,
+        so the convention in ``self._normalize_ops`` is to yield the target first.
         """
         del market
 

src/backtest_lib/engine/plan/__init__.py

@@ -16,6 +16,8 @@ class TradeOrder:
 
     Trade orders are produced by plan generators and executed by a
     :class:`~backtest_lib.engine.execute.PlanExecutor`.
+    ``direction`` and ``qty`` together define the signed position change, while
+    ``price`` is the execution price used to compute cash impact.
     """
 
     direction: TradeDirection
@@ -34,7 +36,12 @@ def cost(self) -> float:
 
 
 class PlanOp:
-    """Marker base class for plan operations."""
+    """Marker base class for plan operations.
+
+    Plan operations are the atomic instructions inside a
+    :class:`~backtest_lib.engine.plan.Plan` that a
+    :class:`~backtest_lib.engine.execute.PlanExecutor` can apply.
+    """
 
     ...
 

src/backtest_lib/market/__init__.py

@@ -222,8 +222,8 @@ class ByPeriod[ValueT: (float, int), Index: Comparable](ABC):
     """Period-axis accessor for a :class:`PastView`.
 
     Provides indexing by period position and slicing by range. A single period
-    access returns a :class:`~backtest_lib.universe.universe_mapping.UniverseMapping`, while
-    slicing returns a new :class:`PastView`.
+    access returns a :class:`~backtest_lib.universe.universe_mapping.UniverseMapping`,
+    while slicing returns a new :class:`PastView`.
     """
 
     @abstractmethod

src/backtest_lib/market/plotting.py

@@ -51,7 +51,8 @@ def line(
 
 
 class UniverseMappingPlotAccessor(ABC):
-    """Plot accessor for :class:`~backtest_lib.universe.universe_mapping.UniverseMapping` data.
+    """Plot accessor for
+    :class:`~backtest_lib.universe.universe_mapping.UniverseMapping` data.
 
     Backends implement this interface to visualize a mapping of securities to
     scalar values. The accessor is available on ``UniverseMapping.plot``.

src/backtest_lib/portfolio/__init__.py

@@ -296,6 +296,9 @@ def uniform_portfolio(
 
 @dataclass(frozen=True, slots=True)
 class Cash:
+    """The type of the cash-only portfolio returned by
+    :func:`~backtest_lib.portfolio.cash`"""
+
     value: float
 
     def materialize(self, universe: Iterable[str], backend: str) -> WeightedPortfolio:
@@ -312,7 +315,19 @@ def materialize(self, universe: Iterable[str], backend: str) -> WeightedPortfoli
         )
 
 
-def cash(value: float):
+def cash(value: float) -> Cash:
+    """Create a cash-only portfolio.
+
+    This can be used as the ``initial_portfolio`` for a
+    :class:`~backtest_lib.backtest.Backtest` when you want to begin with no
+    holdings.
+
+    Args:
+        value: Starting cash value.
+
+    Returns:
+        Cash portfolio with the provided value.
+    """
     return Cash(value=value)