docs: enhance documentation for ProjectX indicators modules with overviews and key features

TexasCoding · CosineGenie · CosineGenie · commit 4bbf104eeb25 · 2025-08-03T03:38:36.000Z
Co-authored-by: Genie &lt;genie@cosine.sh&gt;
diff --git a/src/project_x_py/indicators/__init__.py b/src/project_x_py/indicators/__init__.py
@@ -4,19 +4,41 @@
 Author: TexasCoding
 Date: June 2025
 
-A comprehensive technical analysis library similar to TA-Lib, built on Polars DataFrames.
-Provides both class-based and function-based interfaces for technical indicators.
-
-Example usage:
+Overview:
+    ProjectX Indicators provides a comprehensive, extensible technical analysis library
+    similar to TA-Lib, built on Polars DataFrames. It offers both class-based and
+    function-based interfaces for over 60 technical indicators, with seamless integration
+    for vectorized backtesting and strategy development in ProjectX and beyond.
+
+Key Features:
+    - Wide range of indicators: trend/overlap, momentum, volatility, volume, and patterns
+    - Class-based and TA-Lib-style function interface for flexible usage
+    - All indicators operate on Polars DataFrames for speed and modern analytics
+    - Utilities for indicator discovery, grouping, and docstring access
+    - Clean API and naming convention for easy scripting and research
+
+Example Usage:
+    ```python
     # Class-based interface
-    >>> from project_x_py.indicators import RSI, SMA
-    >>> rsi = RSI()
-    >>> data_with_rsi = rsi.calculate(ohlcv_data, period=14)
+    from project_x_py.indicators import RSI, SMA
+    rsi = RSI()
+    data_with_rsi = rsi.calculate(ohlcv_data, period=14)
 
     # Function-based interface (TA-Lib style)
-    >>> from project_x_py.indicators import calculate_rsi, calculate_sma
-    >>> data_with_rsi = calculate_rsi(ohlcv_data, period=14)
-    >>> data_with_sma = calculate_sma(ohlcv_data, period=20)
+    from project_x_py.indicators import calculate_rsi, calculate_sma
+    data_with_rsi = calculate_rsi(ohlcv_data, period=14)
+    data_with_sma = calculate_sma(ohlcv_data, period=20)
+    ```
+
+See Also:
+    - `project_x_py.indicators.base` (abstract base classes/utilities)
+    - `project_x_py.indicators.momentum`
+    - `project_x_py.indicators.overlap`
+    - `project_x_py.indicators.volume`
+    - `project_x_py.indicators.volatility`
+    - `project_x_py.indicators.order_block`
+    - `project_x_py.indicators.fvg`
+    - `project_x_py.indicators.waddah_attar`
 """
 
 import polars as pl
diff --git a/src/project_x_py/indicators/base.py b/src/project_x_py/indicators/base.py
@@ -4,7 +4,35 @@
 Author: TexasCoding
 Date: June 2025
 
-Base classes and common functionality for technical indicators.
+Overview:
+    Provides abstract base classes and shared validation/utilities for all ProjectX
+    indicator modules. Encapsulates error handling, cache logic, and call semantics
+    for consistent and efficient indicator development. All custom indicators should
+    inherit from these classes for uniformity and extensibility.
+
+Key Features:
+    - `BaseIndicator` with parameter validation, data checks, and result caching
+    - Specialized subclasses: OverlapIndicator, MomentumIndicator, VolatilityIndicator,
+      VolumeIndicator
+    - Utility functions for safe division, rolling sums, and EMA alpha calculation
+    - Standardized exception (`IndicatorError`) for all indicator errors
+
+Example Usage:
+    ```python
+    from project_x_py.indicators.base import BaseIndicator
+
+    class MyCustomIndicator(BaseIndicator):
+        def calculate(self, data, period=10):
+            self.validate_data(data, ["close"])
+            self.validate_period(period)
+            # ... custom calculation ...
+    ```
+
+See Also:
+    - `project_x_py.indicators.momentum.MomentumIndicator`
+    - `project_x_py.indicators.overlap.OverlapIndicator`
+    - `project_x_py.indicators.volatility.VolatilityIndicator`
+    - `project_x_py.indicators.volume.VolumeIndicator`
 """
 
 import hashlib
diff --git a/src/project_x_py/indicators/fvg.py b/src/project_x_py/indicators/fvg.py
@@ -4,8 +4,28 @@
 Author: TexasCoding
 Date: August 2025
 
-Fair Value Gap indicator identifies imbalance areas in price action where there is little
-to no trading activity, which can act as support/resistance zones.
+Overview:
+    Implements the Fair Value Gap (FVG) indicator for identifying price imbalances
+    and potential support/resistance zones. Detects gaps in price action with
+    optional mitigation logic, helping traders spot areas likely to be revisited.
+
+Key Features:
+    - Identifies bullish/bearish fair value gaps from OHLC data
+    - Supports configurable gap size, mitigation threshold, and custom columns
+    - Returns gap boundary, size, and mitigation status for each bar
+    - Callable as a class or via TA-Lib-style convenience function
+
+Example Usage:
+    ```python
+    from project_x_py.indicators import FVG
+    fvg = FVG()
+    data_with_fvg = fvg.calculate(ohlcv_data, min_gap_size=0.001)
+    gaps = data_with_fvg.filter(pl.col("fvg_bullish"))
+    ```
+
+See Also:
+    - `project_x_py.indicators.order_block`
+    - `project_x_py.indicators.base.BaseIndicator`
 """
 
 from typing import Any
diff --git a/src/project_x_py/indicators/momentum.py b/src/project_x_py/indicators/momentum.py
@@ -4,8 +4,29 @@
 Author: TexasCoding
 Date: June 2025
 
-Momentum indicators measure the rate of change in price movements,
-helping identify overbought/oversold conditions and trend strength.
+Overview:
+    Provides a suite of momentum indicators for ProjectX, covering oscillators and
+    trend-following calculations. Includes both class-based and TA-Lib-style
+    function interfaces for RSI, MACD, Stochastic, CCI, and many more, all operating
+    on Polars DataFrames.
+
+Key Features:
+    - Relative Strength Index (RSI), MACD, Stochastic, Williams %R, CCI, ROC, MOM, and more
+    - Directional movement, Aroon, Ultimate Oscillator, and Chande Momentum Oscillator
+    - All indicators vectorized for performance and chained analysis
+    - Flexible configuration: periods, smoothing, columns, and more
+    - Convenient function interface for script-style use
+
+Example Usage:
+    ```python
+    from project_x_py.indicators import calculate_rsi
+    data_with_rsi = calculate_rsi(ohlcv_data, period=14)
+    ```
+
+See Also:
+    - `project_x_py.indicators.base.MomentumIndicator`
+    - `project_x_py.indicators.overlap`
+    - `project_x_py.indicators.volume`
 """
 
 from typing import Any
diff --git a/src/project_x_py/indicators/order_block.py b/src/project_x_py/indicators/order_block.py
@@ -4,8 +4,28 @@
 Author: TexasCoding
 Date: August 2025
 
-Order Block indicator identifies institutional order areas based on price action patterns.
-These are supply and demand zones where large market participants likely have pending orders.
+Overview:
+    Implements the Order Block indicator, which detects likely institutional supply/demand
+    zones from price action and volume. Useful for identifying areas where large orders
+    may cluster, acting as future support or resistance.
+
+Key Features:
+    - Detects bullish and bearish order blocks based on candle/volume logic
+    - Configurable volume threshold, mitigation, and lookback
+    - Outputs block boundaries, strength, and mitigation status per bar
+    - Class and function interfaces for flexible use
+
+Example Usage:
+    ```python
+    from project_x_py.indicators import OrderBlock
+    ob = OrderBlock()
+    data_with_ob = ob.calculate(ohlcv_data, min_volume_percentile=70)
+    ```
+
+See Also:
+    - `project_x_py.indicators.fvg`
+    - `project_x_py.indicators.base.BaseIndicator`
+    - `project_x_py.indicators.volume`
 """
 
 from typing import Any
diff --git a/src/project_x_py/indicators/overlap.py b/src/project_x_py/indicators/overlap.py
@@ -4,8 +4,29 @@
 Author: TexasCoding
 Date: June 2025
 
-Overlap study indicators are often displaced by default and superimposed
-over the main price chart.
+Overview:
+    Contains all trend-following (overlap) indicators for ProjectX, including
+    moving averages, Bollinger Bands, and adaptive smoothing. Each indicator
+    provides a class interface and function-style convenience wrapper, and
+    all outputs are Polars DataFrames for easy chaining.
+
+Key Features:
+    - SMA, EMA, DEMA, TEMA, WMA, TRIMA, KAMA, and other moving averages
+    - Bollinger Bands, Parabolic SAR, Hilbert Transform, and more
+    - Selectable MA type for generic moving average computations
+    - Rolling, exponential, and adaptive implementations
+    - All indicators are vectorized and support chaining
+
+Example Usage:
+    ```python
+    from project_x_py.indicators import calculate_sma
+    data_with_sma = calculate_sma(ohlcv_data, period=20)
+    ```
+
+See Also:
+    - `project_x_py.indicators.base.OverlapIndicator`
+    - `project_x_py.indicators.momentum`
+    - `project_x_py.indicators.volatility`
 """
 
 from typing import Any
diff --git a/src/project_x_py/indicators/volatility.py b/src/project_x_py/indicators/volatility.py
@@ -4,8 +4,28 @@
 Author: TexasCoding
 Date: June 2025
 
-Volatility indicators measure the rate of price fluctuations,
-helping traders understand market volatility and potential breakouts.
+Overview:
+    Implements volatility-focused indicators for ProjectX, quantifying price range,
+    standard deviation, and directional movement. Designed for gauging market
+    turbulence, breakout potential, and risk in systematic strategies.
+
+Key Features:
+    - Average True Range (ATR), ADX, NATR, TRANGE, STDDEV, Ultimate Oscillator
+    - Wilder's smoothing, EMA, and rolling window variants
+    - All indicators operate on Polars DataFrames
+    - TA-Lib-style convenience functions for scripting/backtesting
+    - Can be chained with other indicator modules
+
+Example Usage:
+    ```python
+    from project_x_py.indicators import calculate_atr
+    data_with_atr = calculate_atr(ohlcv_data, period=14)
+    ```
+
+See Also:
+    - `project_x_py.indicators.base.VolatilityIndicator`
+    - `project_x_py.indicators.overlap`
+    - `project_x_py.indicators.momentum`
 """
 
 from typing import Any
diff --git a/src/project_x_py/indicators/volume.py b/src/project_x_py/indicators/volume.py
@@ -4,8 +4,27 @@
 Author: TexasCoding
 Date: June 2025
 
-Volume indicators analyze trading volume to confirm price movements
-and identify potential trend reversals or continuations.
+Overview:
+    Implements volume-based indicators for ProjectX, allowing traders to confirm
+    trends, spot reversals, and analyze money flow. Includes both cumulative
+    and oscillator-style volume indicators operating on Polars DataFrames.
+
+Key Features:
+    - OBV, VWAP, Accumulation/Distribution (AD), AD Oscillator (ADOSC)
+    - Rolling, cumulative, and EMA-based volume analytics
+    - TA-Lib-style function interface for direct scripting
+    - Compatible with all other indicator modules
+
+Example Usage:
+    ```python
+    from project_x_py.indicators import calculate_vwap
+    data_with_vwap = calculate_vwap(ohlcv_data, period=20)
+    ```
+
+See Also:
+    - `project_x_py.indicators.base.VolumeIndicator`
+    - `project_x_py.indicators.momentum`
+    - `project_x_py.indicators.overlap`
 """
 
 from typing import Any
diff --git a/src/project_x_py/indicators/waddah_attar.py b/src/project_x_py/indicators/waddah_attar.py
@@ -4,8 +4,29 @@
 Author: TexasCoding
 Date: August 2025
 
-Waddah Attar Explosion indicator is a volatility-based indicator that combines
-MACD and Bollinger Bands to identify strong trends and potential breakouts.
+Overview:
+    Implements the Waddah Attar Explosion (WAE) indicator for detecting strong
+    trends and breakout conditions. Combines MACD, Bollinger Bands, and ATR-based
+    dead zone logic to filter for high-momentum moves with volatility context.
+
+Key Features:
+    - Computes explosion line, trend, and dead zone from price/volatility data
+    - Configurable MACD/Bollinger/ATR parameters for fine-tuning
+    - Flags bullish/bearish breakouts above dead zone threshold
+    - Callable as a class or with TA-Lib-style convenience function
+
+Example Usage:
+    ```python
+    from project_x_py.indicators import WAE
+    wae = WAE()
+    data_with_wae = wae.calculate(ohlcv_data)
+    signals = data_with_wae.filter(pl.col("wae_explosion_above_dz"))
+    ```
+
+See Also:
+    - `project_x_py.indicators.volatility`
+    - `project_x_py.indicators.base.BaseIndicator`
+    - `project_x_py.indicators.momentum`
 """
 
 from typing import Any
