Merging from Dev

.github/workflows/docs.yml

@@ -9,12 +9,12 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-python@v5
-        with: {python-version: '3.12'}
+        with: {python-version: '3.11'}
       - name: Install dependencies
-        run: pip install "mkdocs-material>=9,<10" pdoc
-      - name: Install package in development mode
-        run: pip install -e .
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install '.[dev]'
       - name: Generate auto-generated API documentation
-        run: python scripts/generate_api_docs.py
+        run: python dev/generate_api_docs.py
       - name: Deploy documentation
         run: mkdocs gh-deploy --force --clean

.github/workflows/publish.yml

@@ -0,0 +1,51 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      test_pypi:
+        description: 'Publish to Test PyPI instead of PyPI'
+        required: false
+        default: false
+        type: boolean
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write  # Required for trusted publishing
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install build dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build twine
+
+      - name: Build package
+        run: python -m build
+
+      - name: Check package
+        run: python -m twine check dist/*
+
+      - name: Publish to Test PyPI
+        if: ${{ github.event.inputs.test_pypi == 'true' }}
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          print-hash: true
+
+      - name: Publish to PyPI
+        if: ${{ github.event_name == 'release' && github.event.action == 'published' }}
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          print-hash: true

.github/workflows/python-test.yml

@@ -1,25 +1,32 @@
-# Run unit tests and check test coverage
-name: Python-test
+# Run tests, linting, and type checking
+name: CI
 
 on: [push, pull_request]
 
 jobs:
-  build:
+  test:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.13"]
+        python-version: ["3.11", "3.12", "3.13"]
 
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
           python -m pip install '.[dev]'
-      - name: Test with pytest and check test coverage
+      - name: Lint with Ruff
         run: |
-          pytest
+          ruff check .
+          ruff format --check .
+      - name: Type check with Pyright
+        run: |
+          pyright
+      - name: Test with pytest and check coverage
+        run: |
+          pytest

.pre-commit-config.yaml

@@ -0,0 +1,24 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.11.13
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/RobertCraigie/pyright-python
+    rev: v1.1.401
+    hooks:
+      - id: pyright
+        args: [--project, pyproject.toml]
+        additional_dependencies: ['geopy', 'networkx', 'pyyaml', 'numpy', 'pandas', 'matplotlib', 'seaborn']
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-merge-conflict
+      - id: check-added-large-files

Makefile

@@ -0,0 +1,177 @@
+# NetGraph Development Makefile
+# This Makefile provides convenient shortcuts for common development tasks
+
+.PHONY: help setup install dev-install check test clean docs build check-dist publish-test publish docker-build docker-run
+
+# Default target - show help
+.DEFAULT_GOAL := help
+
+help:
+	@echo "🔧 NetGraph Development Commands"
+	@echo ""
+	@echo "Setup & Installation:"
+	@echo "  make setup         - Full development environment setup (install + hooks)"
+	@echo "  make install       - Install package in development mode (no dev deps)"
+	@echo "  make dev-install   - Install package with all dev dependencies"
+	@echo ""
+	@echo "Code Quality & Testing:"
+	@echo "  make check         - Run all pre-commit checks and tests"
+	@echo "  make lint          - Run only linting (ruff + pyright)"
+	@echo "  make format        - Auto-format code with ruff"
+	@echo "  make test          - Run tests with coverage"
+	@echo "  make test-quick    - Run tests without coverage"
+	@echo ""
+	@echo "Documentation:"
+	@echo "  make docs          - Generate API documentation"
+	@echo "  make docs-test     - Test API documentation generation"
+	@echo "  make docs-serve    - Serve documentation locally"
+	@echo ""
+	@echo "Build & Package:"
+	@echo "  make build         - Build distribution packages"
+	@echo "  make clean         - Clean build artifacts and cache files"
+	@echo ""
+	@echo "Publishing:"
+	@echo "  make check-dist    - Check distribution packages with twine"
+	@echo "  make publish-test  - Publish to Test PyPI"
+	@echo "  make publish       - Publish to PyPI"
+	@echo ""
+	@echo "Docker (if available):"
+	@echo "  make docker-build  - Build Docker image"
+	@echo "  make docker-run    - Run Docker container with Jupyter"
+	@echo ""
+	@echo "Utilities:"
+	@echo "  make info          - Show project information"
+
+# Setup and Installation
+setup:
+	@echo "🚀 Setting up development environment..."
+	@bash dev/setup-dev.sh
+
+install:
+	@echo "📦 Installing package in development mode (no dev dependencies)..."
+	pip install -e .
+
+dev-install:
+	@echo "📦 Installing package with dev dependencies..."
+	pip install -e '.[dev]'
+
+# Code Quality and Testing
+check:
+	@echo "🔍 Running complete code quality checks and tests..."
+	@bash dev/run-checks.sh
+
+lint:
+	@echo "🧹 Running linting checks..."
+	@pre-commit run ruff --all-files
+	@pre-commit run pyright --all-files
+
+format:
+	@echo "✨ Auto-formatting code..."
+	@pre-commit run ruff-format --all-files
+
+test:
+	@echo "🧪 Running tests with coverage..."
+	@pytest
+
+test-quick:
+	@echo "⚡ Running tests without coverage..."
+	@pytest --no-cov
+
+# Documentation
+docs:
+	@echo "📚 Generating API documentation..."
+	@echo "ℹ️  This regenerates docs/reference/api-full.md from source code"
+	@python dev/generate_api_docs.py --write-file
+
+docs-test:
+	@echo "🧪 Testing API documentation generation..."
+	@python dev/test_doc_generation.py
+
+docs-serve:
+	@echo "🌐 Serving documentation locally..."
+	@if command -v mkdocs >/dev/null 2>&1; then \
+		mkdocs serve; \
+	else \
+		echo "❌ mkdocs not installed. Install dev dependencies with: make dev-install"; \
+		exit 1; \
+	fi
+
+# Build and Package
+build:
+	@echo "🏗️  Building distribution packages..."
+	@if python -c "import build" >/dev/null 2>&1; then \
+		python -m build; \
+	else \
+		echo "❌ build module not installed. Install dev dependencies with: make dev-install"; \
+		exit 1; \
+	fi
+
+clean:
+	@echo "🧹 Cleaning build artifacts and cache files..."
+	@rm -rf build/
+	@rm -rf dist/
+	@rm -rf *.egg-info/
+	@find . -type f -name "*.pyc" -delete
+	@find . -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null || true
+	@find . -type f -name "*.pyo" -delete
+	@find . -type f -name "*~" -delete
+	@find . -type f -name "*.orig" -delete
+	@echo "✅ Cleanup complete!"
+
+# Docker commands (optional)
+docker-build:
+	@echo "🐳 Building Docker image..."
+	@if [ -f "Dockerfile" ]; then \
+		bash run.sh build; \
+	else \
+		echo "❌ Dockerfile not found"; \
+		exit 1; \
+	fi
+
+docker-run:
+	@echo "🐳 Running Docker container with Jupyter..."
+	@if [ -f "run.sh" ]; then \
+		bash run.sh run; \
+	else \
+		echo "❌ run.sh not found"; \
+		exit 1; \
+	fi
+
+# Publishing
+check-dist:
+	@echo "🔍 Checking distribution packages..."
+	@if python -c "import twine" >/dev/null 2>&1; then \
+		python -m twine check dist/*; \
+	else \
+		echo "❌ twine not installed. Install dev dependencies with: make dev-install"; \
+		exit 1; \
+	fi
+
+publish-test:
+	@echo "📦 Publishing to Test PyPI..."
+	@if python -c "import twine" >/dev/null 2>&1; then \
+		python -m twine upload --repository testpypi dist/*; \
+	else \
+		echo "❌ twine not installed. Install dev dependencies with: make dev-install"; \
+		exit 1; \
+	fi
+
+publish:
+	@echo "🚀 Publishing to PyPI..."
+	@if python -c "import twine" >/dev/null 2>&1; then \
+		python -m twine upload dist/*; \
+	else \
+		echo "❌ twine not installed. Install dev dependencies with: make dev-install"; \
+		exit 1; \
+	fi
+
+# Project Information
+info:
+	@echo "📋 NetGraph Project Information"
+	@echo "================================"
+	@echo "Python version: $$(python --version)"
+	@echo "Package version: $$(python -c 'import ngraph; print(ngraph.__version__)' 2>/dev/null || echo 'Not installed')"
+	@echo "Virtual environment: $$(echo $$VIRTUAL_ENV | sed 's|.*/||' || echo 'None active')"
+	@echo "Pre-commit installed: $$(pre-commit --version 2>/dev/null || echo 'Not installed')"
+	@echo "Git status:"
+	@git status --porcelain | head -5 || echo "Not a git repository"

README.md

@@ -11,7 +11,7 @@ NetGraph is a scenario-based network modeling and analysis framework written in
 - **Scenario-Based Modeling** [DONE]: Define complete network scenarios in YAML with topology, failures, traffic, and workflow
 - **Hierarchical Blueprints** [DONE]: Reusable network templates with nested structures and parameterization
 - **Demand Placement** [DONE]: Place traffic demands on the network with various flow placement strategies (e.g., shortest path only, ECMP/UCMP, etc.)
-- **Capacity Calculation** [DONE]: Calculate capacity with different flow placement strategies 
+- **Capacity Calculation** [DONE]: Calculate capacity with different flow placement strategies
 - **Failure Simulation** [DONE]: Model component and risk groups failures for availability analysis
 - **Network Analysis** [IN PROGRESS]: Analyze capacity, failure tolerance, and efficiency
 

dev/dev.md

@@ -0,0 +1,66 @@
+# NetGraph Development Guide
+
+## Essential Commands
+
+```bash
+make setup         # Complete dev environment setup
+make check         # Run all quality checks + tests
+make test          # Run tests with coverage
+make docs          # Generate API documentation
+make docs-serve    # Serve docs locally
+```
+
+**For all available commands**: `make help`
+
+## Documentation
+
+### Generating API Documentation
+
+The API documentation is auto-generated from source code docstrings:
+
+```bash
+# Generate API documentation
+make docs
+# or
+python dev/generate_api_docs.py
+```
+
+**Important**: API documentation is **not** regenerated during pytest runs to avoid constant file changes. The doc generation test is skipped by default. To test doc generation:
+
+```bash
+GENERATE_DOCS=true pytest tests/test_api_docs.py::test_api_doc_generation_output
+```
+
+### Documentation Types
+
+- `docs/reference/api.md` - Curated, example-driven API guide (manually maintained)
+- `docs/reference/api-full.md` - Complete auto-generated reference (regenerated via `make docs`)
+- `docs/reference/cli.md` - Command-line interface documentation
+- `docs/reference/dsl.md` - YAML DSL syntax reference
+
+## Publishing
+
+**Manual**: `make clean && make build && make publish-test && make publish`
+
+**Automated**: Create GitHub release → auto-publishes to PyPI
+
+**Version**: Update `version = "x.y.z"` in `pyproject.toml` before publishing
+
+## Key Development Files
+
+```
+pyproject.toml              # Package config, dependencies, tool settings
+Makefile                    # Development commands
+.pre-commit-config.yaml     # Code quality hooks
+dev/setup-dev.sh           # Development environment setup script
+dev/run-checks.sh           # Manual code quality checks
+```
+
+## Git Workflows
+
+```
+.github/workflows/
+├── python-test.yml         # CI: tests, linting, type checking
+├── docs.yml                # Auto-deploy documentation
+└── publish.yml             # Auto-publish to PyPI on releases
+```