Stellium Documentation¶

Welcome to the Stellium documentation! This directory contains comprehensive guides, references, and galleries for the Stellium astrology library.

Getting Started¶

New to Stellium? Start with the main README for installation, quick start, and progressive examples.

User Guides¶

Document	Description
VISUALIZATION.md	Complete guide to chart drawing: themes, palettes, presets, tables, and the fluent API
REPORTS.md	Report generation guide: sections, presets, PDF output with Typst, comparison reports
CHART_TYPES.md	Chart types: natal, synastry, transit, composite, Davison, unknown time

Visual Galleries¶

Gallery	Description
THEME_GALLERY.md	Visual showcase of all 13+ chart themes (classic, dark, midnight, celestial, neon, etc.)
PALETTE_GALLERY.md	Zodiac ring color palettes: rainbow, elemental, scientific colormaps

Technical Documentation¶

The full developer reference lives in development/ — a per-subsystem API/architecture guide written primarily for coding agents (and handy for contributors). See the complete map in DOCS_INDEX.md.

Document	Description
development/	Architecture + API reference (chart building, engines, components, visualization, reports, extending)
DOCS_INDEX.md	Complete index of all documentation
ARCHITECTURE.md	⚠️ Superseded historical architecture doc (kept for concepts only)

Package publishing is maintainer-only and documented in CONTRIBUTING.md.

Example Cookbooks¶

Runnable Python scripts in /examples:

Cookbook	Description
chart_cookbook.py	21 examples: basic charts, themes, palettes, house systems, tables
report_cookbook.py	15 examples: terminal reports, PDF generation, synastry reports
comparison_cookbook.py	13 examples: synastry, transits, bi-wheels, compatibility scoring

# Run any cookbook
python examples/chart_cookbook.py
python examples/report_cookbook.py
python examples/comparison_cookbook.py

Developer Reference (`/development/`)¶

The durable architecture + API reference, written primarily for coding agents (see each file’s “Hello, Claude!” callout) but useful to any contributor.

Document	Description
README.md	Reading order and scope of the developer docs
ARCHITECTURE.md	Mental model, layer map, dependency rules, `.calculate()` flow
CHART_BUILDING.md	`Native`/`Notable`, `ChartBuilder`, `CalculatedChart`, config, registries
ENGINES.md	Ephemeris, houses, aspects, orbs, dignities, patterns, profections
COMPONENTS_AND_ANALYSIS.md	Components, analysis/DataFrames, IO, caching, utils
VISUALIZATION_INTERNALS.md	SVG pipeline, layers, themes/palettes, dial/vedic/atlas
PRESENTATION_INTERNALS.md	`ReportBuilder`, sections, renderers
SUBSYSTEMS.md	Multi-chart, returns, electional, planner, Chinese/BaZi, CLI
EXTENDING.md	Adding engines/components/analyzers/layers/themes/sections

`/scripts/`¶

Script	Description
chart_visualization_doc_examples.py	Generates all chart images for documentation

Quick Links¶

Main README - Project overview, installation, quick start
CONTRIBUTING.md - How to contribute
CHANGELOG.md - Release history
TODO.md - Development roadmap

Project Structure¶

stellium/
├── README.md                 # Main project documentation
├── CONTRIBUTING.md           # Contribution guidelines
├── CHANGELOG.md              # Release history
├── TODO.md                   # Development roadmap
│
├── docs/                     # This documentation directory
│   ├── VISUALIZATION.md      # Chart drawing guide
│   ├── REPORTS.md            # Report generation guide
│   ├── CHART_TYPES.md        # Chart types guide
│   ├── THEME_GALLERY.md      # Visual theme gallery
│   ├── PALETTE_GALLERY.md    # Zodiac palette gallery
│   ├── ARCHITECTURE.md       # Superseded architecture doc (historical)
│   ├── DOCS_INDEX.md         # Index of all documentation
│   ├── development/          # Developer/agent API & architecture reference
│   ├── scripts/              # Doc generation scripts
│   └── images/               # Documentation images
│
├── examples/                 # Runnable example scripts
│   ├── chart_cookbook.py     # Chart visualization examples
│   ├── report_cookbook.py    # Report generation examples
│   ├── comparison_cookbook.py # Synastry/transit examples
│   ├── charts/               # Generated chart output
│   ├── reports/              # Generated report output
│   └── comparisons/          # Generated comparison output
│
├── src/stellium/             # Core library code
│   ├── core/                 # Core models and builders
│   ├── engines/              # Calculation engines
│   ├── components/           # Optional components
│   ├── visualization/        # Chart rendering
│   └── presentation/         # Report generation
│
└── tests/                    # Test suite

For the latest updates, see the main README.md