From 5ecd3b7cb58a8fa43ee694a5b3fe69a32fcf3c2b Mon Sep 17 00:00:00 2001 From: Nicholas Karlson Date: Wed, 21 Jan 2026 12:17:41 -0800 Subject: [PATCH] Docs: Track D BYOD polish (placeholders, PyPI-first copy, nav) --- docs/source/workbook/index.rst | 2 - docs/source/workbook/track_d_byod.rst | 28 +++++++++--- docs/source/workbook/track_d_byod_gnucash.rst | 43 +++++++++++-------- .../track_d_byod_gnucash_demo_analysis.rst | 19 +++++--- 4 files changed, 60 insertions(+), 32 deletions(-) diff --git a/docs/source/workbook/index.rst b/docs/source/workbook/index.rst index 9ce2786..d34e5df 100644 --- a/docs/source/workbook/index.rst +++ b/docs/source/workbook/index.rst @@ -20,7 +20,5 @@ PyStatsV1 Workbook track_d_outputs_guide track_d_my_own_data track_d_byod - track_d_byod_gnucash - track_d_byod_gnucash_demo_analysis track_d_assignments track_d_lab_ta_notes diff --git a/docs/source/workbook/track_d_byod.rst b/docs/source/workbook/track_d_byod.rst index 2b1fd85..81342ea 100644 --- a/docs/source/workbook/track_d_byod.rst +++ b/docs/source/workbook/track_d_byod.rst @@ -7,7 +7,7 @@ Track D BYOD: Bring Your Own Data Track D is built around a realistic accounting case study (NSO), but the *skills* are meant to transfer. This BYOD (Bring Your Own Data) pipeline lets you take **real exports** (from a bookkeeping/accounting system) -and convert them into the same **Track D dataset contract** used in the workbook. +and convert them into the same **Track D dataset contract** used in the workbook. In the commands below, replace with your project folder (for example: byod/gnucash_demo). What “BYOD” means in Track D ---------------------------- @@ -23,13 +23,18 @@ The core idea is: *separate the messy export from the clean analysis tables*. Quick start (template) ---------------------- +If an option name ever changes, the source of truth is always the CLI help: + +- ``pystatsv1 trackd byod --help`` +- ``pystatsv1 trackd byod init --help`` + Create a BYOD project folder (this writes header-only templates under ``tables/``): .. code-block:: console - pystatsv1 trackd byod init --dest byod/my_project --profile core_gl + pystatsv1 trackd byod init --dest --profile core_gl -Edit ``byod/my_project/config.toml`` to choose an adapter (examples): +Edit ``/config.toml`` to choose an adapter (examples): - ``adapter = "passthrough"`` — your ``tables/`` files are already in Track D’s canonical format - ``adapter = "core_gl"`` — generic GL export adapter (varies by source) @@ -39,18 +44,21 @@ Then normalize: .. code-block:: console - pystatsv1 trackd byod normalize --project byod/my_project + pystatsv1 trackd byod normalize --project + + # (optional) override profile explicitly + pystatsv1 trackd byod normalize --project --profile core_gl You should now have: -- ``byod/my_project/normalized/chart_of_accounts.csv`` -- ``byod/my_project/normalized/gl_journal.csv`` +- ``/normalized/chart_of_accounts.csv`` +- ``/normalized/gl_journal.csv`` Validate the normalized tables: .. code-block:: console - pystatsv1 trackd validate --datadir byod/my_project/normalized --profile core_gl + pystatsv1 trackd validate --datadir /normalized --profile core_gl PyPI-only setup (no Git required) ---------------------------------------------- @@ -80,6 +88,12 @@ If you just want to *use* Track D tools (you don’t need to clone the repo): pystatsv1 doctor +Need a reminder of commands? + +.. code-block:: console + + pystatsv1 trackd byod --help + Next: choose a tutorial ----------------------- diff --git a/docs/source/workbook/track_d_byod_gnucash.rst b/docs/source/workbook/track_d_byod_gnucash.rst index f7e7243..a326779 100644 --- a/docs/source/workbook/track_d_byod_gnucash.rst +++ b/docs/source/workbook/track_d_byod_gnucash.rst @@ -4,7 +4,10 @@ Track D BYOD with GnuCash (core_gl profile) =========================================== -GnuCash is a **free, open-source** double-entry accounting system. +GnuCash is a **free, open-source** double-entry accounting system. + +Note that in the commands below, replace with your project folder (for example: byod/gnucash_demo). + In Track D, we use it as a “real but accessible” source system: - it produces realistic **multi-line split** exports (not toy spreadsheets) @@ -87,7 +90,9 @@ From any folder you like (your BYOD projects can live anywhere): .. code-block:: console - pystatsv1 trackd byod init --dest byod/gnucash_demo --profile core_gl + pystatsv1 trackd byod init --dest --profile core_gl + +Need a reminder of options? Run: ``pystatsv1 trackd byod init --help`` This creates: @@ -100,7 +105,7 @@ Step 5 — Point the project at the GnuCash adapter Open: -``byod/gnucash_demo/config.toml`` +``/config.toml`` Change: @@ -116,26 +121,27 @@ Step 6 — Place your export in the expected location Copy your GnuCash export CSV to: -``byod/gnucash_demo/tables/gl_journal.csv`` +``/tables/gl_journal.csv`` Yes, the file is called ``gl_journal.csv`` even though it is still “raw export.” The adapter reads this file and writes the canonical tables to ``normalized/``. -If you want to test without GnuCash, copy the demo export instead: +If you downloaded the demo export from this page (PyPI users), copy it into place: -If you installed PyStatsV1 from PyPI (no repo clone), download **"Demo export (complex/multi-line)"** above -and copy that file to ``byod/gnucash_demo/tables/gl_journal.csv``. +.. code-block:: console -If you have the repo source code, you can copy the demo export from this docs folder: + # Windows (PowerShell) + Copy-Item "" (Join-Path "" "tables\gl_journal.csv") + # Windows (Git Bash) + cp "" "/tables/gl_journal.csv" -.. code-block:: console + # macOS/Linux + cp "" "/tables/gl_journal.csv" - # (Windows PowerShell) - copy docs\source\workbook\_downloads\gnucash_demo\gnucash_demo_export_complex.csv byod\gnucash_demo\tables\gl_journal.csv +If you have the repo source code, the same demo export also lives here: - # (macOS/Linux) - cp docs/source/workbook/_downloads/gnucash_demo/gnucash_demo_export_complex.csv byod/gnucash_demo/tables/gl_journal.csv +- ``docs/source/workbook/_downloads/gnucash_demo/gnucash_demo_export_complex.csv`` Step 7 — Normalize ------------------ @@ -144,19 +150,22 @@ Run: .. code-block:: console - pystatsv1 trackd byod normalize --project byod/gnucash_demo + pystatsv1 trackd byod normalize --project + + # (optional) override profile explicitly + pystatsv1 trackd byod normalize --project --profile core_gl You should now have: -- ``byod/gnucash_demo/normalized/chart_of_accounts.csv`` -- ``byod/gnucash_demo/normalized/gl_journal.csv`` +- ``/normalized/chart_of_accounts.csv`` +- ``/normalized/gl_journal.csv`` Step 8 — Validate the normalized tables --------------------------------------- .. code-block:: console - pystatsv1 trackd validate --datadir byod/gnucash_demo/normalized --profile core_gl + pystatsv1 trackd validate --datadir /normalized --profile core_gl Step 9 — Do a first analysis ---------------------------- diff --git a/docs/source/workbook/track_d_byod_gnucash_demo_analysis.rst b/docs/source/workbook/track_d_byod_gnucash_demo_analysis.rst index cd13cb7..cc5c408 100644 --- a/docs/source/workbook/track_d_byod_gnucash_demo_analysis.rst +++ b/docs/source/workbook/track_d_byod_gnucash_demo_analysis.rst @@ -27,20 +27,25 @@ If you want to jump straight to analysis without running the normalization step Option A — Build daily totals from your normalized tables --------------------------------------------------------- -Assume your BYOD project is at ``byod/gnucash_demo`` and you have: +Assume your BYOD project is at ```` and you have: -- ``byod/gnucash_demo/normalized/gl_journal.csv`` -- ``byod/gnucash_demo/normalized/chart_of_accounts.csv`` +- ``/normalized/gl_journal.csv`` +- ``/normalized/chart_of_accounts.csv`` Run the built-in helper: .. code-block:: console - pystatsv1 trackd byod daily-totals --project byod/gnucash_demo + pystatsv1 trackd byod daily-totals --project + + # (optional) choose an explicit output path + pystatsv1 trackd byod daily-totals --project --out /normalized/daily_totals.csv + +Need a reminder of options? Run: ``pystatsv1 trackd byod daily-totals --help`` This writes: -- ``byod/gnucash_demo/normalized/daily_totals.csv`` +- ``/normalized/daily_totals.csv`` Option B — Quick first analysis (no repo clone required) -------------------------------------------------------- @@ -55,7 +60,9 @@ This snippet prints a few summary stats and writes a simple plot: import matplotlib.pyplot as plt from pathlib import Path - csv_path = Path("byod/gnucash_demo/normalized/daily_totals.csv") + project = Path("byod/gnucash_demo") # <-- set to your BYOD project folder (e.g., "") + + csv_path = project / "normalized" / "daily_totals.csv" outdir = Path("outputs/gnucash_demo") outdir.mkdir(parents=True, exist_ok=True)