Update preface and quick start guide

[jdecarolis]

Rewrote large portions of preface.rst and updated the database description in quick_start.rst.

Summary by CodeRabbit

• Documentation
  • Greatly expanded the overview and motivations to explain core capabilities, time modeling, stochastic options, MGA, licensing, storage, Python integration, and ecosystem.
  • Reworked "Why" section with historical context and community focus.
  • Reorganized Quick Start to emphasize a relational-database workflow, primary/foreign keys, data integrity, and updated example guidance.
  • Editorial and formatting improvements for clarity and consistency.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

Extended documentation content: docs/source/preface.rst now has a much longer description of Temoa’s purpose, structure, time/stochastic features, licensing, storage, and ecosystem; docs/source/quick_start.rst was refocused from DAT-file examples to a relational (SQL/SQLite) schema approach with updated examples and paths.

Changes

Cohort / File(s)	Summary
Documentation narrative expansion docs/source/preface.rst	Replaced concise ESOM description with an expanded narrative detailing Temoa’s ESOM nature, time modeling (period types, e/f), stochastic and MGA approaches, optimization notes, MIT licensing, SQLite storage, Python integration, and historical/community context.
Quick Start restructuring docs/source/quick_start.rst	Rewrote quick-start to emphasize relational DB schema over DAT files: introduced table/primary-foreign key explanations, new time_period schema and inserts, clarified data integrity, updated example dataset/schema paths (e.g., example_dbs/utopia.sql, temoa_schema_v4.sql), and adjusted phrasing/formatting for config and outputs.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Suggested labels

docs

Pre-merge checks

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly and accurately describes the main changes: updates to preface.rst and quick_start.rst documentation files.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 5ddcf8b and 5d85d6b.

📒 Files selected for processing (2)

• docs/source/preface.rst
• docs/source/quick_start.rst

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (4)

• GitHub Check: setup and test (macos-latest, 3.13)
• GitHub Check: setup and test (macos-latest, 3.12)
• GitHub Check: setup and test (windows-latest, 3.12)
• GitHub Check: setup and test (windows-latest, 3.13)

🔇 Additional comments (3)

docs/source/quick_start.rst (3)

129-176: Database explanation is clear and well-presented.

The introduction to relational databases, primary keys, foreign keys, and referential integrity is accurate and appropriately tailored for an introductory audience. The emphasis on using databases to catch typos through constraints is practical and valuable.

---

139-155: SQL example is syntactically correct.

The CREATE TABLE and INSERT examples follow SQLite conventions correctly. The primary key definition and foreign key constraint are properly structured.

---

226-231: File path references are accurate and verified.

Both updated file paths referenced in the documentation exist in the repository:

• data_files/example_dbs/utopia.sql ✓
• data_files/temoa_schema_v4.sql ✓

No action needed.

[coderabbitai]

Actionable comments posted: 1

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 5d85d6b and 9186a05.

📒 Files selected for processing (2)

• docs/source/preface.rst
• docs/source/quick_start.rst

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (4)

• GitHub Check: setup and test (macos-latest, 3.12)
• GitHub Check: setup and test (macos-latest, 3.13)
• GitHub Check: setup and test (windows-latest, 3.12)
• GitHub Check: setup and test (windows-latest, 3.13)

🔇 Additional comments (5)

docs/source/preface.rst (1)

19-87: Substantial improvement to preface documentation.

The expansion of the "What is Temoa?" and "Why Temoa?" sections significantly enhances clarity. The rewrite provides:

• Clear ESOM definition with concrete optimization objectives and constraints
• Detailed explanation of Temoa's time-flexibility features (seasonality, vintaging, discount rates, stochastic/MGA support)
• Well-motivated historical context (2009 motivations) explaining the open-source rationale
• Strong narrative alignment with the broader ecosystem component description

The previous spelling errors ("seemlessly" and "inpout data") have been corrected. Documentation quality is notably improved.

docs/source/quick_start.rst (4)

129-176: Excellent introduction to relational database concepts for documentation users.

The new database fundamentals section clearly explains primary/foreign keys and data consistency with a concrete time_period table example. The explanation of foreign key constraints and their role in preventing data-entry errors is particularly well-suited for a quick-start guide—it educates users on why the schema is structured a certain way, not just how to use it.

---

181-224: Clear and logically structured database population guidance.

The four-group ordering (labels → sets → parameters for processes → parameters for constraints) reflects proper foreign-key dependency sequencing and provides users with actionable guidance. The categorization is pedagogically sound and helps users understand schema design rationale.

---

245-299: Comprehensive data quality validation documentation.

The Data Quality section provides clear explanations of six price-checking categories and the source-tracing orphan detection mechanism. The progression from simpler checks (missing costs) to sophisticated validation (lifetime costing, network tracing) is appropriate for the audience. The note about myopic mode dependency on source tracing (line 298) is important and well-placed.

---

226-239: File paths are accurate and verified. Both data_files/example_dbs/utopia.sql and data_files/temoa_schema_v4.sql exist in the repository at the locations referenced in the documentation. No action required.

[coderabbitai]

Actionable comments posted: 1

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 9186a05 and 3753005.

📒 Files selected for processing (2)

• docs/source/preface.rst
• docs/source/quick_start.rst

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (4)

• GitHub Check: setup and test (windows-latest, 3.13)
• GitHub Check: setup and test (macos-latest, 3.12)
• GitHub Check: setup and test (windows-latest, 3.12)
• GitHub Check: setup and test (macos-latest, 3.13)

🔇 Additional comments (6)

docs/source/preface.rst (2)

19-63: Documentation expansion is well-crafted and comprehensive.

The newly expanded "What is Temoa?" section (lines 19–63) provides excellent context on Temoa's purpose, technical structure, time-modeling capabilities, optimization approaches (including stochastic and MGA), open-source licensing, SQLite data storage, and ecosystem components. The writing is clear, logically organized, and reinforces the relational-database framing now emphasized in quick_start.rst.

---

69-87: "Why Temoa?" section adds valuable historical and motivational context.

The revised section (lines 69–87) effectively contextualizes Temoa's creation in 2009, articulates the market gap it addresses, and clearly states three high-level objectives (open-source code/data, open-source software stack, uncertainty evaluation toolkit). This narrative grounds the project's mission and complements the technical description above.

docs/source/quick_start.rst (4)

129-176: Database construction explanation is clear and educationally sound.

The reframed database section (lines 129–176) effectively introduces relational concepts (primary keys, foreign keys, relationships) in accessible language, then grounds them with a concrete SQL example of the time_period table. The explanation of how foreign keys catch typos and enforce consistency is practical and motivating.

---

178-225: Table population guidance is well-organized and logical.

The grouping of database tables into four priority groups (lines 178–225) reflects proper dependency ordering and helps users understand which tables to populate first. The rationale for each group (labels, sets, parameters, constraints) is clear.

---

226-239: Updated file paths and schema guidance are current and helpful.

The updated references to data_files/example_dbs/utopia.sql and data_files/temoa_schema_v4.sql provide clear, concrete starting points. The guidance on converting SQL to SQLite (lines 232–236) and setting the database as the config data source is practical.

---

245-300: Data quality section provides comprehensive QA and consistency checks.

The price checking and source tracing sections (lines 252–300) are detailed, well-organized, and explain the purpose and scope of each check. The emphasis on catching omissions and network gaps is valuable for users building large datasets.