Skip to content

fix(docs): correct stale h5ad examples in cli.py docstrings - #40

Merged
Claptar merged 1 commit into
cellgeni:mainfrom
iamcipherdev:fix/help-examples-h5ad-rename-2026-10-15
Oct 15, 2026
Merged

Claptar merged 1 commit into
cellgeni:mainfrom
iamcipherdev:fix/help-examples-h5ad-rename-2026-10-15

Conversation

@iamcipherdev

Copy link
Copy Markdown
Contributor

Closes #38

Several Examples: blocks in src/adata/cli.py still used the pre-rename h5ad command name, and export sparse / export image showed a positional output that the commands reject (output goes to -o or 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 every adata ... example line in the --help text (real command + real options, including short flags). I verified the new check fails on the pre-fix h5ad lines and passes after; 283 tests pass in the two touched test files.

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 Claptar left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@Claptar
Claptar merged commit dd4b4b1 into cellgeni:main Oct 15, 2026
4 checks passed
@Claptar Claptar mentioned this pull request Oct 15, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

Help examples in cli.py still say h5ad, and two of them don't run

2 participants