Enhanced examples with detailed comments, numbered files, and README …

.github/workflows/publish-pypi.yml

@@ -4,6 +4,10 @@ on:
   push:
     tags:
       - 'v*'
+  workflow_run:
+    workflows: ["CI Pipeline"]
+    types:
+      - completed
 
 permissions:
   contents: write
@@ -12,6 +16,7 @@ permissions:
 jobs:
   build-and-publish:
     runs-on: ubuntu-latest
+    if: ${{ github.event.workflow_run.conclusion == 'success' || github.event_name == 'push' }}
 
     steps:
     - name: Checkout code

docs/README.md

@@ -0,0 +1,81 @@
+# MeridianAlgo Documentation
+
+This directory contains comprehensive documentation for the MeridianAlgo package.
+
+## Documentation Files
+
+### index.md
+Main documentation homepage with overview and quick links.
+
+### installation.md
+Installation instructions for different platforms and use cases.
+
+### quickstart.md
+Quick start guide to get up and running in minutes.
+
+### API_REFERENCE.md
+Complete API reference for all modules and functions.
+
+### benchmarks.md
+Performance benchmarks and optimization guidelines.
+
+## API Documentation
+
+### api/portfolio_management.md
+Documentation for portfolio optimization and management:
+- Portfolio optimization algorithms
+- Risk parity
+- Black-Litterman model
+- Hierarchical Risk Parity (HRP)
+- Rebalancing strategies
+
+### api/technical_indicators.md
+Documentation for technical analysis:
+- Moving averages
+- Momentum indicators
+- Volatility indicators
+- Volume indicators
+- Custom indicator creation
+
+## Building Documentation
+
+If you have Sphinx installed, you can build HTML documentation:
+
+```bash
+cd docs
+pip install -r requirements.txt
+sphinx-build -b html . _build
+```
+
+## Documentation Structure
+
+```
+docs/
+├── README.md                    # This file
+├── index.md                     # Documentation homepage
+├── installation.md              # Installation guide
+├── quickstart.md               # Quick start tutorial
+├── API_REFERENCE.md            # Complete API reference
+├── benchmarks.md               # Performance benchmarks
+├── api/
+│   ├── portfolio_management.md # Portfolio API docs
+│   └── technical_indicators.md # Technical analysis API docs
+├── examples/                   # Example code snippets
+└── requirements.txt            # Documentation dependencies
+```
+
+## Contributing to Documentation
+
+When adding new features:
+1. Update relevant API documentation
+2. Add examples to demonstrate usage
+3. Update the quickstart if it's a core feature
+4. Add benchmarks for performance-critical code
+
+## Documentation Standards
+
+- Use clear, concise language
+- Include code examples for all features
+- Explain the "why" not just the "how"
+- Link to related functions and concepts
+- Keep examples self-contained and runnable

examples/01_getting_started.py

@@ -0,0 +1,143 @@
+"""
+Getting Started with MeridianAlgo
+==================================
+
+This example walks you through the basics of using MeridianAlgo for quantitative
+finance analysis. We'll cover data fetching, basic calculations, and visualization.
+
+Perfect for: Beginners who want to understand the fundamentals
+Time to run: ~30 seconds
+"""
+
+import meridianalgo as ma
+
+print("Welcome to MeridianAlgo!")
+print("=" * 60)
+
+# ============================================================================
+# Step 1: Fetching Market Data
+# ============================================================================
+print("\nStep 1: Fetching Market Data")
+print("-" * 60)
+
+# Let's grab some stock data for popular tech companies
+# We're using the last year of data to keep things manageable
+tickers = ["AAPL", "MSFT", "GOOGL"]
+print(f"Fetching data for: {', '.join(tickers)}")
+
+try:
+    # get_market_data is your one-stop shop for historical price data
+    # It automatically handles data cleaning and formatting
+    prices = ma.get_market_data(tickers, start="2023-01-01", end="2024-01-01")
+
+    print(f"✓ Successfully fetched {len(prices)} days of data")
+    print(f"  Date range: {prices.index[0]} to {prices.index[-1]}")
+    print("\nFirst few prices:")
+    print(prices.head())
+
+except Exception as e:
+    print(f"✗ Error fetching data: {e}")
+    print("  Make sure you have an internet connection!")
+    exit(1)
+
+# ============================================================================
+# Step 2: Calculating Returns
+# ============================================================================
+print("\nStep 2: Calculating Returns")
+print("-" * 60)
+
+# Returns are the percentage change in price from one day to the next
+# This is what we actually care about for most financial analysis
+returns = prices.pct_change().dropna()
+
+print("Daily returns calculated!")
+print(f"  Total observations: {len(returns)}")
+print("\nAverage daily returns:")
+for ticker in tickers:
+    avg_return = returns[ticker].mean()
+    annual_return = (1 + avg_return) ** 252 - 1  # Annualize it
+    print(f"  {ticker}: {avg_return:.4%} daily ({annual_return:.2%} annualized)")
+
+# ============================================================================
+# Step 3: Risk Analysis
+# ============================================================================
+print("\n⚠️  Step 3: Risk Analysis")
+print("-" * 60)
+
+# Volatility tells us how much the price bounces around
+# Higher volatility = more risk (but potentially more reward)
+print("Volatility (annualized standard deviation):")
+for ticker in tickers:
+    vol = returns[ticker].std() * (252**0.5)  # Annualize volatility
+    print(f"  {ticker}: {vol:.2%}")
+
+# Sharpe Ratio: Return per unit of risk (higher is better)
+# A Sharpe > 1 is generally considered good
+print("\nSharpe Ratios (return/risk):")
+for ticker in tickers:
+    mean_return = returns[ticker].mean() * 252
+    volatility = returns[ticker].std() * (252**0.5)
+    sharpe = mean_return / volatility if volatility > 0 else 0
+    print(f"  {ticker}: {sharpe:.2f}")
+
+# ============================================================================
+# Step 4: Correlation Analysis
+# ============================================================================
+print("\nStep 4: Correlation Analysis")
+print("-" * 60)
+
+# Correlation shows how stocks move together
+# 1.0 = perfect correlation, 0 = no correlation, -1.0 = inverse correlation
+correlation = returns.corr()
+print("Correlation matrix:")
+print(correlation.round(3))
+
+print("\nWhat this means:")
+print("  Values close to 1.0: Stocks move together (diversification benefit is low)")
+print("  Values close to 0.0: Stocks move independently (good for diversification)")
+print("  Values close to -1.0: Stocks move opposite (great for hedging)")
+
+# ============================================================================
+# Step 5: Simple Portfolio
+# ============================================================================
+print("\nStep 5: Building a Simple Portfolio")
+print("-" * 60)
+
+# Let's create an equal-weighted portfolio
+# This means we invest the same amount in each stock
+weights = [1 / len(tickers)] * len(tickers)
+print(f"Portfolio weights: {dict(zip(tickers, weights, strict=False))}")
+
+# Calculate portfolio returns
+portfolio_returns = (returns * weights).sum(axis=1)
+
+# Portfolio statistics
+portfolio_mean = portfolio_returns.mean() * 252
+portfolio_vol = portfolio_returns.std() * (252**0.5)
+portfolio_sharpe = portfolio_mean / portfolio_vol if portfolio_vol > 0 else 0
+
+print("\nPortfolio Performance:")
+print(f"  Expected Annual Return: {portfolio_mean:.2%}")
+print(f"  Annual Volatility: {portfolio_vol:.2%}")
+print(f"  Sharpe Ratio: {portfolio_sharpe:.2f}")
+
+# Compare to individual stocks
+print("\nComparison:")
+print(f"  Portfolio volatility ({portfolio_vol:.2%}) is lower than individual stocks")
+print("  This is the power of diversification!")
+
+# ============================================================================
+# Summary
+# ============================================================================
+print("\n" + "=" * 60)
+print("Congratulations! You've completed the basics!")
+print("=" * 60)
+print("\nWhat you learned:")
+print("  ✓ How to fetch market data")
+print("  ✓ How to calculate returns and risk metrics")
+print("  ✓ How to analyze correlations")
+print("  ✓ How to build a simple portfolio")
+print("\nNext steps:")
+print("  → Try 02_portfolio_optimization.py for advanced portfolio techniques")
+print("  → Explore 03_risk_management.py to learn about VaR and risk metrics")
+print("  → Check out 04_technical_analysis.py for trading indicators")