Repository navigation
fix(docs): correct stale h5ad examples in cli.py docstrings - #40
Conversation
Export/import Examples: blocks still used the pre-rename 'h5ad' command name, and 'export sparse'/'export image' examples took a positional output the commands reject (output goes to -o/stdout). Fixed all six blocks and extended tests/test_docs_are_accurate.py to validate every 'adata ...' example in the --help text against the real Click tree (real command + real options), so this drift is caught in CI. Closes cellgeni#38
Claptar
left a comment
There was a problem hiding this comment.
Thanks for this. The docstring fixes look right, and a test that walks every --help example is a good guard to have.
One non-blocking note. test_help_examples_name_real_commands_and_options checks that the command path resolves and that each option is real. It doesn't check the number of positional arguments, though. So an example like adata export sparse data.h5ad X matrix.mtx, with a stray positional output, would pass as long as it starts with adata. That was half of what #38 reported.
Click can do that check for you. For each example, resolve the command, then call command.make_context(name, args) with the remaining tokens. That raises click.UsageError on an unexpected extra argument, a missing required one, or an unknown option, so it could also replace the hand-rolled option check. Happy to take that as a follow-up if you'd rather keep this PR as it is.
Closes #38
Several
Examples:blocks insrc/adata/cli.pystill used the pre-renameh5adcommand name, andexport sparse/export imageshowed a positional output that the commands reject (output goes to-oor stdout). All six blocks fixed per the issue.Also extended
tests/test_docs_are_accurate.py: it now walks the real Click tree and validates everyadata ...example line in the--helptext (real command + real options, including short flags). I verified the new check fails on the pre-fixh5adlines and passes after; 283 tests pass in the two touched test files.