Docs: Track D BYOD polish (placeholders, PyPI-first copy, nav)

Author: nicholaskarlson

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

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 <BYOD_DIR> 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 <BYOD_DIR> --profile core_gl
 
-Edit ``byod/my_project/config.toml`` to choose an adapter (examples):
+Edit ``<BYOD_DIR>/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 <BYOD_DIR>
+
+   # (optional) override profile explicitly
+   pystatsv1 trackd byod normalize --project <BYOD_DIR> --profile core_gl
 
 You should now have:
 
-- ``byod/my_project/normalized/chart_of_accounts.csv``
-- ``byod/my_project/normalized/gl_journal.csv``
+- ``<BYOD_DIR>/normalized/chart_of_accounts.csv``
+- ``<BYOD_DIR>/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 <BYOD_DIR>/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
 -----------------------
 

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 <BYOD_DIR> 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 <BYOD_DIR> --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``
+``<BYOD_DIR>/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``
+``<BYOD_DIR>/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 "<PATH_TO_DOWNLOADED_EXPORT_CSV>" (Join-Path "<BYOD_DIR>" "tables\gl_journal.csv")
 
+   # Windows (Git Bash)
+   cp "<PATH_TO_DOWNLOADED_EXPORT_CSV>" "<BYOD_DIR>/tables/gl_journal.csv"
 
-.. code-block:: console
+   # macOS/Linux
+   cp "<PATH_TO_DOWNLOADED_EXPORT_CSV>" "<BYOD_DIR>/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 <BYOD_DIR>
+
+   # (optional) override profile explicitly
+   pystatsv1 trackd byod normalize --project <BYOD_DIR> --profile core_gl
 
 You should now have:
 
-- ``byod/gnucash_demo/normalized/chart_of_accounts.csv``
-- ``byod/gnucash_demo/normalized/gl_journal.csv``
+- ``<BYOD_DIR>/normalized/chart_of_accounts.csv``
+- ``<BYOD_DIR>/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 <BYOD_DIR>/normalized --profile core_gl
 
 Step 9 — Do a first analysis
 ----------------------------

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 ``<BYOD_DIR>`` and you have:
 
-- ``byod/gnucash_demo/normalized/gl_journal.csv``
-- ``byod/gnucash_demo/normalized/chart_of_accounts.csv``
+- ``<BYOD_DIR>/normalized/gl_journal.csv``
+- ``<BYOD_DIR>/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 <BYOD_DIR>
+
+   # (optional) choose an explicit output path
+   pystatsv1 trackd byod daily-totals --project <BYOD_DIR> --out <BYOD_DIR>/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``
+- ``<BYOD_DIR>/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., "<BYOD_DIR>")
+
+   csv_path = project / "normalized" / "daily_totals.csv"
    outdir = Path("outputs/gnucash_demo")
    outdir.mkdir(parents=True, exist_ok=True)