docs: add a three-track user manual and absorb the existing user guide (#428) - #429
Open
w7-mgfcode wants to merge 2 commits into
Open
docs: add a three-track user manual and absorb the existing user guide (#428)#429w7-mgfcode wants to merge 2 commits into
w7-mgfcode wants to merge 2 commits into
Conversation
…428) Add docs/manual/ — 23 chapters across an operator, analyst, and integrator track, plus shared configuration, troubleshooting, FAQ, and glossary references. Each chapter carries a Purpose / Intended reader pair, a "What you'll accomplish" section, and a Next pointer. Stated numbers trace to app/core/config.py, a fixed constant, or an authoritative module; runtime figures are explained rather than asserted. Corrects two drifts found against the code while writing: - the model list was 7 types; app/shared/model_taxonomy.py defines 11 - the data-platform table count was 7; there are 10 Six user-guide files become redirect stubs. showcase-manual-demo-guide.md (reviewer QA procedure) and showcase-walkthrough.md (unshipped roadmap) are kept intact with a pointer banner — neither is user-manual content. Every internal link and anchor resolves; no chapter is orphaned.
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Sorry @w7-mgfcode, your pull request is larger than the review limit of 150000 diff characters
|
Important Review skippedAuto reviews are disabled on base/target branches other than the default branch. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Plus Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
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. Comment |
Contributor
Reviewer's GuideAdds a new three-track user manual under docs/manual/, migrates and redirects the previous user-guide content into it, and corrects documented model and data-platform counts against authoritative code sources, leaving two non-manual guides intact with pointer banners. File-Level Changes
Possibly linked issues
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
Ran the stack end to end and checked the quickstart chapter against real
output. Four corrections:
- /health returns {"status":"ok","database":null}, not {"status":"ok"}.
Fixed in installation, troubleshooting, and api-reference. (The root
README carries the same inaccuracy.)
- `docker compose up -d` starts postgres, backend AND frontend — only
ollama is profile-gated. Host-mode instructions now name the service:
`docker compose up -d postgres`.
- The demo trains three baselines (naive, seasonal_naive,
moving_average), so its winner says nothing about feature-aware
models. Removed the misleading implication and pointed at the champion
selector for real comparisons.
- reset/agent/cleanup legitimately report skip and the run still exits 0
GREEN. Documented skips as non-failures.
Adds a troubleshooting entry for "Multiple head revisions are present",
which breaks `alembic upgrade head`, the backend container's startup
command, and `make demo`.
Verified as correct: exit code 2 on precondition failure, the 11-step
pipeline order, the summary-line format, SHA-256 artifact verification,
graceful agent skip without an API key, and seed reproducibility — a
re-run on seed 42 reproduced the row count, date range, selected pair,
and WAPE to four decimals.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #428.
Adds
docs/manual/— a navigable user manual organised into three tracks — and folds the existingdocs/user-guide/into it.Why three tracks
IntentGuard's manual uses two (operator / integrator). ForecastLabAI needs a third: it has a dashboard-analyst persona who never opens a terminal, and folding those chapters into the operator track buries them.
23 chapters, ~26k words.
Conventions
Every chapter carries a
Purpose:/Intended reader:header pair, a "What you'll accomplish" section, dense cross-linking, and a "Next" pointer — so any chapter is a valid entry point.Evidence discipline. Stated numbers trace to
app/core/config.py, a fixed constant, or an authoritative module (app/shared/model_taxonomy.py,app/shared/feature_frames/contract_v2.py). Runtime-dependent figures — durations, accuracy, which model wins — are explained rather than asserted, since they depend on data, seed, and hardware. The synthetic-data caveat is stated once inoperator/concepts.mdand referenced rather than repeated.Drift corrected
Found by checking the old guide against the code:
feature-reference.mdlisted 7;_MODEL_FAMILY_MAPdefines 11 — 5 baseline, 4 tree, 2 additive. (weighted_moving_average,seasonal_average,random_forest,trend_regression_baselinewere missing.)exogenous_signal,replenishment_event,sales_returns).Same class of drift as #376 (stale slice count in
docs/_base/). The manual states 19 slices and 23 tables, both verified.Disposition of docs/user-guide/
Six guides → short redirect stubs pointing at their new chapters.
Two are kept intact with only a pointer banner added, because neither is user-manual content:
showcase-manual-demo-guide.md— a reviewer QA procedure.showcase-walkthrough.md— contains an unshippedPlanned (PRP-38..41)roadmap.Validation
docs/manual/anddocs/user-guide/resolves to an existing file.Docs-only change — no application code touched, so the lint/type/test gates are unaffected.
Summary by Sourcery
Introduce a new three-track user manual under docs/manual and fold the existing user-guide content into it with validated, up-to-date information on models, tables, configuration, operations, and workflows.
Documentation: