From 2b2516de7195dc429cb3d44dc7b067265bc3861f Mon Sep 17 00:00:00 2001 From: Nicholas Karlson Date: Wed, 14 Jan 2026 00:09:55 -0800 Subject: [PATCH] Docs: add workbook learning path + artifacts reference + troubleshooting --- docs/source/workbook/index.rst | 26 ++++-- docs/source/workbook/student_quick_start.rst | 7 ++ .../workbook/workbook_artifacts_reference.rst | 77 +++++++++++++++++ .../workbook_check_your_work_pack.rst | 6 +- .../workbook/workbook_learning_path.rst | 48 +++++++++++ .../workbook/workbook_troubleshooting.rst | 83 +++++++++++++++++++ 6 files changed, 239 insertions(+), 8 deletions(-) create mode 100644 docs/source/workbook/workbook_artifacts_reference.rst create mode 100644 docs/source/workbook/workbook_learning_path.rst create mode 100644 docs/source/workbook/workbook_troubleshooting.rst diff --git a/docs/source/workbook/index.rst b/docs/source/workbook/index.rst index 2ea9f98..f4f62fd 100644 --- a/docs/source/workbook/index.rst +++ b/docs/source/workbook/index.rst @@ -12,18 +12,32 @@ This workbook teaches *intro* financial accounting using a simple hybrid workflo .. toctree:: :maxdepth: 2 + :caption: Start here student_quick_start - workbook_spreadsheet_first_overview + workbook_learning_path 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 - intro_zero_cost_stack + workbook_artifacts_reference + workbook_troubleshooting + +.. toctree:: + :maxdepth: 1 + :caption: Workbook chapters (hybrid method) + ch01_startup ch01_equation_transaction ch02_journal_to_trial_balance ch03_adjusting_entries ch04_closing_and_post_close + +.. toctree:: + :maxdepth: 2 + :caption: Optional tracks and packs + + workbook_spreadsheet_first_overview + workbook_spreadsheet_first_ch01_ch04 + workbook_spreadsheet_build_ch01_ch04 + workbook_data_pack_ch01_startup + workbook_check_your_work_pack + intro_zero_cost_stack diff --git a/docs/source/workbook/student_quick_start.rst b/docs/source/workbook/student_quick_start.rst index b471d1c..72bc263 100644 --- a/docs/source/workbook/student_quick_start.rst +++ b/docs/source/workbook/student_quick_start.rst @@ -33,6 +33,13 @@ These files appear under: .. note:: LedgerLoom runs best inside a **virtual environment** (venv). This keeps your class setup clean and repeatable. +Where to go next +---------------- + +- :doc:`workbook_learning_path` — the “golden path” for this course +- :doc:`workbook_artifacts_reference` — what each output CSV means +- :doc:`workbook_troubleshooting` — common errors and quick fixes + Linux (Ubuntu/Debian) --------------------- diff --git a/docs/source/workbook/workbook_artifacts_reference.rst b/docs/source/workbook/workbook_artifacts_reference.rst new file mode 100644 index 0000000..dad1f37 --- /dev/null +++ b/docs/source/workbook/workbook_artifacts_reference.rst @@ -0,0 +1,77 @@ +Workbook Artifacts Reference +============================ + +LedgerLoom produces two kinds of outputs: + +1) **Check outputs** (fast feedback) — written by ``ledgerloom check`` +2) **Run outputs** (a full snapshot) — written by ``ledgerloom build --run-id `` + +Check outputs (``outputs/check//``) +------------------------------------------- + +These files help you fix problems *before* you build a run folder: + +- ``checks.md`` + A human-readable report: what LedgerLoom found, and what to do next. + +- ``staging.csv`` + Your inputs normalized into a consistent table format. + +- ``staging_issues.csv`` + Row-level problems (missing fields, invalid dates, bad numbers). + +- ``unmapped.csv`` + Rows LedgerLoom could not map cleanly (often an account name mismatch). + +- ``reclass_template.csv`` + A “fill-in-the-blanks” template used for reclassing/mapping workflows. + +Run outputs (``outputs//artifacts/``) +--------------------------------------------- + +These are the canonical workbook artifacts you compare against your spreadsheet: + +- ``entries.csv`` + Your journal entries in a normalized, deterministic format. + +- ``trial_balance_unadjusted.csv`` + Trial balance after posting **transactions** only. + +- ``trial_balance_adjusted.csv`` + Trial balance after posting **transactions + adjustments**. + +- ``closing_entries.csv`` + The closing entry set that resets temporary accounts (revenue/expenses/dividends). + +- ``trial_balance_post_close.csv`` + Post-close trial balance (balance-sheet accounts only). + +Where “trust” fits (``outputs//trust/``) +------------------------------------------------ + +LedgerLoom also writes a trust package (hashes + manifests) so a run folder is a +reproducible snapshot. + +As a student, you usually only need this when: + +- you’re submitting a “run folder” as proof, or +- you want to confirm you built against the intended inputs. + +If you’re curious, start with: + +- ``trust/run_meta.json`` — what was built, when, and from which sources +- ``trust/manifest.json`` — the list of artifacts and their hashes + +How to use this page while working +---------------------------------- + +If something breaks: + +1) run ``ledgerloom check`` +2) open ``outputs/check//checks.md`` +3) fix the first error you see, then re-run + +If you’re unsure which output to compare: + +- use **trial balances** to validate totals +- use **entries.csv** to validate the “shape” of the journal (dates, accounts, signs) diff --git a/docs/source/workbook/workbook_check_your_work_pack.rst b/docs/source/workbook/workbook_check_your_work_pack.rst index 2aebb9f..1dbf4b1 100644 --- a/docs/source/workbook/workbook_check_your_work_pack.rst +++ b/docs/source/workbook/workbook_check_your_work_pack.rst @@ -1,10 +1,12 @@ -Optional: Check Your Work Pack (Ch01 Startup) -============================================= +Optional: Check Your Work Packs (Ch01–Ch04) +=========================================== This workbook is meant to be a *learning* experience, not a “gotcha” test. If you have a low tolerance for frustration (or you just want to confirm you’re on the right track), use the downloads below to compare your work against a known-good reference. +These packs are available for **Ch01–Ch04** and include a completed spreadsheet plus reference outputs. + **Canonical dataset contract:** each Workbook chapter has a *canonical dataset* under ``examples/workbook//`` — treat this as the answer key. The accompanying “reference outputs” ZIPs are generated by running ``ledgerloom build --run-id r1`` for that diff --git a/docs/source/workbook/workbook_learning_path.rst b/docs/source/workbook/workbook_learning_path.rst new file mode 100644 index 0000000..e507b76 --- /dev/null +++ b/docs/source/workbook/workbook_learning_path.rst @@ -0,0 +1,48 @@ +Workbook Learning Path (Spreadsheet + LedgerLoom) +================================================= + +This is the **main path** for the workbook: you do the accounting in your spreadsheet, +then use LedgerLoom to verify it and produce clean CSV artifacts you can compare. + +The loop you will repeat +------------------------ + +1) **Draft** in Sheets/Excel (transactions + adjustments + optional closing). +2) **Export CSVs** using the workbook template headers. +3) Run: + + .. code-block:: bash + + ledgerloom check --project . + ledgerloom build --project . --run-id run1 + +4) **Reconcile**: compare your spreadsheet totals to LedgerLoom outputs. Fix mistakes, re-run. + +Where to start +-------------- + +If you are brand new, do this in order: + +- :doc:`student_quick_start` (install + your first run) +- :doc:`ch01_startup` (a runnable, known-good project) +- :doc:`ch02_journal_to_trial_balance` (journal → TB) +- :doc:`ch03_adjusting_entries` (accrual adjustments → adjusted TB) +- :doc:`ch04_closing_and_post_close` (closing → post-close TB) + +If you want to learn the accounting cycle **without any tooling first**, use the +Spreadsheet-First track: :doc:`workbook_spreadsheet_first_overview`. + +What “success” looks like +------------------------- + +- ``ledgerloom check`` produces a review package under ``outputs/check//``. +- ``ledgerloom build --run-id run1`` produces a full run folder under ``outputs/run1/``. +- Your spreadsheet and LedgerLoom artifacts should agree on totals (trial balance and post-close TB). + +Next: learn the output files +---------------------------- + +Before you go deeper, skim: + +- :doc:`workbook_artifacts_reference` — what each CSV output means +- :doc:`workbook_troubleshooting` — common mistakes and how to recover quickly diff --git a/docs/source/workbook/workbook_troubleshooting.rst b/docs/source/workbook/workbook_troubleshooting.rst new file mode 100644 index 0000000..45b318f --- /dev/null +++ b/docs/source/workbook/workbook_troubleshooting.rst @@ -0,0 +1,83 @@ +Workbook Troubleshooting +======================== + +This page is a student-friendly checklist for the most common problems. + +I ran ``ledgerloom check`` and it failed +---------------------------------------- + +Start here: + +1) Open ``outputs/check//checks.md``. +2) Fix the *first* issue listed (later issues often cascade from earlier ones). +3) Run ``ledgerloom check`` again. + +I can’t find my outputs +----------------------- + +- ``ledgerloom check`` writes to: ``outputs/check//`` +- ``ledgerloom build --run-id run1`` writes to: ``outputs/run1/`` + +Your workbook artifacts live in: + +- ``outputs//artifacts/`` + +I see ``unmapped.csv`` +---------------------- + +This usually means LedgerLoom didn’t recognize something in your inputs (often an +account name mismatch). + +Do this: + +1) Open ``outputs/check//unmapped.csv``. +2) Compare the ``account`` values to ``config/chart_of_accounts.yaml``. +3) Fix the spelling / punctuation / account root (``Assets:``, ``Liabilities:``, etc.). +4) Re-run ``ledgerloom check``. + +My trial balance doesn’t balance +-------------------------------- + +If your spreadsheet trial balance debits ≠ credits: + +- Look for a sign error (debit entered as credit or vice versa). +- Look for a missing “pair” row in a journal entry (every entry must balance). +- Compare your spreadsheet journal lines against ``outputs//artifacts/entries.csv``. + +I used ``--run-id`` with ``check`` and got an error +--------------------------------------------------- + +``--run-id`` belongs to ``build``, not ``check``: + +.. code-block:: bash + + ledgerloom check --project . + ledgerloom build --project . --run-id run1 + +LedgerLoom says an account root is invalid +------------------------------------------ + +LedgerLoom expects account names to start with one of these roots: + +- ``Assets:`` +- ``Liabilities:`` +- ``Equity:`` +- ``Revenue:`` +- ``Expenses:`` + +Example: + +- ✅ ``Assets:Cash`` +- ❌ ``Cash`` (missing root) + +Still stuck? +------------ + +- Re-run ``ledgerloom check`` and read ``checks.md`` carefully. +- If you are working from a workbook chapter, compare against the + :doc:`workbook_check_your_work_pack`. +- If you think it’s a bug, open an issue on GitHub with: + + - your LedgerLoom version (``ledgerloom --version``) + - the ``checks.md`` file + - a minimal set of inputs that reproduces the issue