docs+gate: correct fluid plugins examples + teach the docs-honesty gate about CLI commands#14
Merged
Merged
Conversation
…te about CLI commands
The `fluid plugins list` example listed 4 providers under a "(5)" header (omitted
`odps`) — verified against the real command, which prints aws/gcp/local/odps/snowflake.
And your-first-real-plugin.md claimed PluginMetadata identity "surfaces to `fluid
plugins list`" — it does not (the command reads entry-point names + allow/block status
only and never loads the plugin). Both corrected.
Extends tests/unit/test_docs_honesty.py (previously blind to CLI-command-example drift,
which is how a fabricated table slipped through):
- test_documented_cli_commands_exist: asserts every `fluid <command>` in a doc code
fence is a real CLI subcommand, via argparse introspection. Runs only when the
data-product-forge CLI is importable; SKIPS with a clear reason in CLI-less SDK CI
("validate where feasible"). Borrowed the argparse-introspection pattern; diverged
from clitest/cram (which run the binary) since this zero-dep SDK doesn't install it.
- test_fluid_plugins_output_advertises_no_impossible_columns: feasible WITHOUT the CLI
— a documented `fluid plugins` block cannot advertise VERSION/AUTHOR/DESCRIPTION
columns the command can't emit. Pins exactly the drift class this PR fixes.
Verified both checks catch injected regressions (fabricated command + the old
VERSION/AUTHOR/DESCRIPTION table) then go green. 156 tests pass (+1 skip in CLI-less CI).
fas89
added a commit
that referenced
this pull request
Jun 27, 2026
…not a provider (#15) Cascade of forge-cli #298 (ODPS reclassified out of the provider registry). PR #14 had added odps to the plug-into-fluid-cli.md 'fluid plugins list' example under 'provider (5)'; ODPS (Open Data Product Standard) is a spec / export format, not a cloud provider, and has now been de-registered, so the real output is 'provider (4)': aws/gcp/local/snowflake. Verified against the merged CLI.
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
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.
What & why
Fixes two real
fluid plugins-related doc inaccuracies and teaches the docs-honestygate about CLI-command-example drift (the class it was structurally blind to).
Doc corrections (verified against the real command)
plug-into-fluid-cli.md: thefluid plugins listexample listed 4 providersunder a
(5)header —odpswas missing. I ran the real command against alatest-
mainCLI venv: it prints aws / gcp / local / odps / snowflake. Fixed.your-first-real-plugin.md: the comment claimedPluginMetadataidentity"surfaces to
fluid plugins list" — it does not. The command reads entry-pointnames + allow/block status only and never loads the plugin. Comment corrected to
say these fields feed registry/marketplace tooling, not
fluid plugins list.Docs-honesty gate extension (the bonus)
test_documented_cli_commands_exist: everyfluid <command>in a doc code fencemust be a real CLI subcommand (argparse introspection). Runs only when the
data-product-forgeCLI is importable; skips with a clear reason in CLI-lessSDK CI ("validate where feasible").
test_fluid_plugins_output_advertises_no_impossible_columns: feasible withoutthe CLI — a documented
fluid pluginsblock cannot advertise VERSION/AUTHOR/DESCRIPTION columns the command can't emit. Pins exactly this PR's drift class.
Borrow-before-build
Surveyed clitest / cram / markdown-clitest / cli-unit / mktestdocs (run-the-binary
doc testers) + the pytest argparse-introspection pattern. Adapted introspection;
diverged from clitest/cram — they need the
fluidbinary present, but thiszero-dependency SDK doesn't (and shouldn't) install the CLI in its CI.
Verification
fluid plugins liston a latest-mainCLI venv) toconfirm the corrected output.
fluid totallyfakecmdfails thecommand check; injecting the old VERSION/AUTHOR/DESCRIPTION table fails the output
guard — both green after revert.
ruff+blackclean.build_parserintrospection is first-party and runs only when the CLI is installed.