Spaces:

sk851
/

TerraFin

Running

TerraFin / docs /development.md

docs: add structured docs site and agent guides

9fe4fad about 1 month ago

2.54 kB

title: Development Guide
summary: Local workflow for code, docs, tests, notebooks, and frontend changes.

Development Guide

This page is the maintainer-facing companion to the product docs.

Path	Purpose
`src/TerraFin/data/`	Data providers, normalization, and output types
`src/TerraFin/analytics/`	Indicators, DCF, risk, options, portfolio, and simulation helpers
`src/TerraFin/interface/`	FastAPI app, page routes, and frontend
`src/TerraFin/agent/`	External-agent client, hosted runtime, model runtime, and tools
`docs/`	Formal documentation site source
`tests/`	Automated regression coverage
`notebooks/`	Manual and demo notebooks only

pip install -e ".[dev]"

Add extras when needed:

pip install -e ".[db]"
pip install -e ".[notebooks]"
pip install -e ".[docs]"

Core Python tests:

pytest

Agent-focused slice:

pytest tests/agent tests/interface/test_agent_api.py

Packaging smoke:

python -m build
python scripts/package_smoke.py

The frontend lives under src/TerraFin/interface/frontend/.

Typical commands:

npm install
npm run build

When you touch page-specific agent context, DCF workbenches, or the hosted assistant widget, verify both desktop and mobile flows.

TerraFin now ships a formal static docs site using MkDocs Material.

Preview locally:

pip install -e ".[docs]"
mkdocs serve

Build locally:

mkdocs build --strict

GitHub Pages deployment is defined in .github/workflows/docs-pages.yml.

Notebooks are for human-guided exploration, not automated tests.

keep notebooks under notebooks/
do not use a test_ prefix for notebook filenames
promote stable notebook logic into tests/test_*.py if it becomes regression-critical

Detailed notebook guidance lives in Notebooks.

Some code-adjacent references remain useful even though they are not formal docs pages: