docs: 'Choosing the Right Options' feature-discovery guide#204
Conversation
The CLI reference (sphinx-click) documents every flag, but a user with a *problem* can't easily tell which feature solves it. Add a problem->feature map covering speed, relational data, idempotency, resilience, messy data, deadlocks, and hierarchies, linking to the in-depth guides. Wired early in the guides toctree.
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a new guide, choosing_options.md, which maps common import problems to specific fluvo features and links to relevant in-depth guides. It also updates the guides index to include this new document. Feedback was provided to use HTML entities (|) instead of backslash-escaped pipes inside the Markdown table to ensure consistent rendering across different Markdown engines.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
| |---|---| | ||
| | (automatic two-pass) | Relational fields are deferred to a second pass to avoid inverse-relation rewrites ([Performance Tuning](performance_tuning.md)) | | ||
| | `--deferred-fields` / `--auto-defer` | Manually or automatically defer specific relational fields | | ||
| | `--check-refs fail\|warn\|skip` | Pre-import validation that referenced XML IDs exist | |
There was a problem hiding this comment.
In Markdown tables, using a backslash to escape a pipe character (\|) inside inline code can sometimes render the backslash literally (as \|) or cause parsing issues depending on the Markdown engine.\n\nUsing the HTML entity | is the standard, most portable way to represent a pipe character inside a table cell without breaking the table structure or rendering an unwanted backslash.
| | `--check-refs fail\|warn\|skip` | Pre-import validation that referenced XML IDs exist | | |
| | `--check-refs fail|warn|skip` | Pre-import validation that referenced XML IDs exist | |
Backslash-escaped pipes (\|) can render literally or break tables on some markdown engines; the HTML entity is portable.
|
Done — replaced the two |
1 participant
Output of the docs/discoverability pass.
The gap
A doc audit found that while the CLI reference is complete (sphinx-click auto-documents every flag's
--help), there's no conceptual entry point: a user with a problem ("my import is slow", "I'm hitting deadlocks", "my source data is messy") has to scroll ~40 flags to find the right one. The powerful features (--resolve-relation,--skip-unchanged,--adaptive-throttle,--check-refs,--auto-clean, ...) were discoverable only by reading the full reference.The fix
A new "Choosing the Right Options" guide — a problem→feature map grouped by intent:
Each row names the flag + what it does, linking to the in-depth guides and the CLI reference. Wired early in the guides toctree as a discovery aid. Builds clean (0 new warnings).
Note: links target the guide files (not section anchors) because
myst_heading_anchorsisn't enabled — robust and warning-free.