From a1e18d84bd94cb7dda42b1c5a37c34fd5b5c8477 Mon Sep 17 00:00:00 2001 From: Nicholas Karlson Date: Tue, 13 Jan 2026 20:54:51 -0800 Subject: [PATCH] Docs: workbook-first UX + fix check/run-id examples --- docs/source/index.rst | 25 ++++++++--------- docs/source/workbook/index.rst | 10 +++---- docs/source/workbook/student_quick_start.rst | 23 +++++++++++++-- .../workbook/workbook_project_layout.rst | 28 +++++++++++++++++-- src/ledgerloom/cli.py | 4 +-- src/ledgerloom/docs_helper.py | 2 +- 6 files changed, 66 insertions(+), 26 deletions(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index 6462419..6b733e7 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -5,12 +5,19 @@ LedgerLoom is a small open-source project (MIT license) that teaches accounting *and* modern software engineering by building a deterministic, testable ledger pipeline. -The documentation is organized into: +If you are using LedgerLoom as a student, start with the **Workbook**. -- **Start here**: what LedgerLoom is and where it is going -- **Engine**: the reusable core that powers the chapters -- **Chapters**: runnable scripts that generate reproducible artifacts -- **Appendices**: reference material (data model, glossary, cookbook) +.. toctree:: + :maxdepth: 2 + :caption: Workbook (Students) + + workbook/index + +.. toctree:: + :maxdepth: 2 + :caption: Practical Tooling (CLI) + + practical_tooling/index .. toctree:: :maxdepth: 1 @@ -59,13 +66,6 @@ The documentation is organized into: ledgerloom_ch17_statement_analysis_summary_statistics ledgerloom_ch18_forecasting_planning_basics - -.. toctree:: - :maxdepth: 1 - :caption: Workbook (Hybrid method) - - workbook/index - .. toctree:: :maxdepth: 1 :caption: Appendices @@ -75,4 +75,3 @@ The documentation is organized into: ledgerloom_appendix_cookbook ledgerloom_appendix_implementation_notes ledgerloom_appendix_data_model_reference - practical_tooling/index diff --git a/docs/source/workbook/index.rst b/docs/source/workbook/index.rst index a7fae51..2ea9f98 100644 --- a/docs/source/workbook/index.rst +++ b/docs/source/workbook/index.rst @@ -2,7 +2,7 @@ Financial Accounting — The Hybrid Method with LedgerLoom ======================================================== **Subtitle:** Stop Guessing. Start Reconciling. -**Version:** 1.0 (compatible with LedgerLoom v0.2.0) +**Version:** 1.0 (compatible with LedgerLoom v0.3.0) This workbook teaches *intro* financial accounting using a simple hybrid workflow: @@ -13,14 +13,14 @@ This workbook teaches *intro* financial accounting using a simple hybrid workflo .. toctree:: :maxdepth: 2 + student_quick_start workbook_spreadsheet_first_overview - workbook_spreadsheet_first_ch01_ch04 - workbook_data_pack_ch01_startup - workbook_spreadsheet_build_ch01_ch04 workbook_onboarding workbook_project_layout + workbook_spreadsheet_first_ch01_ch04 + workbook_spreadsheet_build_ch01_ch04 + workbook_data_pack_ch01_startup workbook_check_your_work_pack - student_quick_start intro_zero_cost_stack ch01_startup ch01_equation_transaction diff --git a/docs/source/workbook/student_quick_start.rst b/docs/source/workbook/student_quick_start.rst index 1b06f01..b471d1c 100644 --- a/docs/source/workbook/student_quick_start.rst +++ b/docs/source/workbook/student_quick_start.rst @@ -25,6 +25,11 @@ These files appear under: - ``outputs//artifacts/`` +.. note:: + ``ledgerloom check`` writes a standalone report folder to ``outputs/check//`` (fast feedback). + ``ledgerloom build --run-id run1`` writes a complete run folder to ``outputs/run1/`` and repeats the + checks inside ``outputs/run1/check/`` for provenance. + .. note:: LedgerLoom runs best inside a **virtual environment** (venv). This keeps your class setup clean and repeatable. @@ -72,7 +77,7 @@ Linux (Ubuntu/Debian) .. code-block:: bash - ledgerloom check --project . --run-id run1 + ledgerloom check --project . ledgerloom build --project . --run-id run1 6) View your outputs @@ -80,6 +85,10 @@ Linux (Ubuntu/Debian) .. code-block:: bash + # Standalone check output (fast feedback) + ls -1 outputs/check + + # Build output (a named run folder) ls -1 outputs/run1/artifacts Common gotchas (Linux) @@ -150,7 +159,7 @@ Then activate again: .. code-block:: powershell - ledgerloom check --project . --run-id run1 + ledgerloom check --project . ledgerloom build --project . --run-id run1 6) View your outputs @@ -158,6 +167,10 @@ Then activate again: .. code-block:: powershell + # Standalone check output (fast feedback) + dir outputs\check + + # Build output (a named run folder) dir outputs\run1\artifacts Common gotchas (Windows) @@ -216,7 +229,7 @@ Then: .. code-block:: bash - ledgerloom check --project . --run-id run1 + ledgerloom check --project . ledgerloom build --project . --run-id run1 6) View your outputs @@ -224,6 +237,10 @@ Then: .. code-block:: bash + # Standalone check output (fast feedback) + ls -1 outputs/check + + # Build output (a named run folder) ls -1 outputs/run1/artifacts Common gotchas (macOS) diff --git a/docs/source/workbook/workbook_project_layout.rst b/docs/source/workbook/workbook_project_layout.rst index 716f0e2..5e5e8e6 100644 --- a/docs/source/workbook/workbook_project_layout.rst +++ b/docs/source/workbook/workbook_project_layout.rst @@ -24,7 +24,17 @@ A typical workbook project looks like this: transactions.csv adjustments.csv outputs/ + check/ + 2026-01/ + checks.md + staging.csv + staging_issues.csv + unmapped.csv + reclass_template.csv run1/ + source_snapshot/ + check/ + trust/ artifacts/ entries.csv trial_balance_unadjusted.csv @@ -51,10 +61,19 @@ What each part means ``inputs//adjustments.csv`` Your adjusting entries table (often empty at the start of Chapter 1). +``outputs/check//`` + The report folder produced by ``ledgerloom check`` when run by itself. + +``outputs//`` + The folder produced by ``ledgerloom build --run-id ``. + ``outputs//artifacts/`` The CSV results LedgerLoom generates. These are meant to be opened in Excel/Sheets and compared to your workbook. +``outputs//check/`` + The same check output, captured inside a build run for provenance. + What is a run_id? ----------------- @@ -99,7 +118,10 @@ Common workflow (what you actually do) .. code-block:: bash - ledgerloom check --project my_books --run-id run1 + ledgerloom check --project my_books + + # Standalone check output is written to: + # my_books/outputs/check// 3) Build artifacts: @@ -107,6 +129,9 @@ Common workflow (what you actually do) ledgerloom build --project my_books --run-id run1 + # Build output is written to: + # my_books/outputs/run1/ + 4) Open artifacts in Excel/Sheets and compare. If something is wrong, don’t panic @@ -129,4 +154,3 @@ Next: Student Quick Start Go to: :doc:`student_quick_start` - diff --git a/src/ledgerloom/cli.py b/src/ledgerloom/cli.py index f5cdddb..8cecc29 100644 --- a/src/ledgerloom/cli.py +++ b/src/ledgerloom/cli.py @@ -94,7 +94,7 @@ def build_parser() -> argparse.ArgumentParser: ) b = sub.add_parser( "build", - help="Create a run folder (snapshot + check + trust + postings + trial_balance + statements)", + help="Create a run folder (snapshot + check + trust + artifacts)", ) b.add_argument( "--project", @@ -280,7 +280,7 @@ def main(argv: Sequence[str] | None = None) -> int: parts.append("trial_balance") if inc.exists() and bs.exists(): parts.append("statements") - print(f"Build OK ({' + '.join(parts)}). Next: closing entries.") + print(f"Build OK ({' + '.join(parts)}). See artifacts/ for generated CSVs.") return 0 diff --git a/src/ledgerloom/docs_helper.py b/src/ledgerloom/docs_helper.py index 4e32a4d..74a54b9 100644 --- a/src/ledgerloom/docs_helper.py +++ b/src/ledgerloom/docs_helper.py @@ -46,4 +46,4 @@ def open_local_docs() -> None: def open_online_docs() -> None: """Open the Read the Docs site for LedgerLoom.""" - webbrowser.open_new("https://ledgerloom.readthedocs.io/en/latest/") + webbrowser.open_new("https://ledgerloom.readthedocs.io/en/latest/workbook/student_quick_start.html")