Open aeisenbarth opened 3 months ago
Those test failures look real. I do wonder if this is really the best way to do this though, and I could envision things getting out of hand relatively quickly. I'm assuming most people are not going more than 3-4 levels deep. This being the case, couldn't you simply document the top level command with :nested: none
and then document the subcommands with :nested: full
and :commands: {commands filter}
? It's a bit of duplication in your docs but unless you've dozens of commands what harm (and if you do, a super long :commands:
option probably isn't the way). I'd also be open to adding other :nested:
values to allow e.g. full display but only for the first level of subcommands.
I'd also be open to adding other
:nested:
values to allow e.g. full display but only for the first level of subcommands.
There's some prior art for this at #109, which I really need to review.
Those test failures look real.
You are right, unfortunately the actions log does not show what exactly failed. I locally got ruff/mypy failures and was worried how they could be caused by my changes, but then I checked the master commit (before mine) and they happened there already. I have not yet looked into how to fix them.
This being the case, couldn't you simply document the top level command with
:nested: none
and then document the subcommands with:nested: full
and:commands: {commands filter}
? In principle, that way also works, just adds some extra code and repetition (although automated is always a bit nicer). But it would leave the inconsistency that:nested:
with other options works differently at the first vs. deeper levels. Other users might encounter the same situation.
Those test failures look real.
You are right, unfortunately the actions log does not show what exactly failed. I locally got ruff/mypy failures and was worried how they could be caused by my changes, but then I checked the master commit (before mine) and they happened there already. I have not yet looked into how to fix them.
The mypy failures are fixed on master now. The tests failures are another matter though :smile:
Indeed! And it was a tricky one!
The single test alone passes, but when all tests are run together, one fails. That is because sphinx-click's _load_module
tries to load a module of the same name "greet" for each test from a different root. But once it has been loaded for root/basics, it is taken from the cache afterward. The other tests used to pass with the wrong greet
module because the implementation was almost equal.
Summary
The
commands
option currently allows to filter commands only at the first nesting level. When CLIs have deeper level of subcommands there is no way to filter or order them apart from writing a directive for each subcommand.This change passes the
commands
option to nested commands. As previously, if a command name at the CLI's top level occurs in the option, it is not documented. If a command name at any deeper level occurs in the option, it is now also excluded.Tasks
reno
)tox
)Further details
(or with another delimiter like
command1.subcommand1
)I considered adding a unit test in
CommandFilterTestCase
. However all those tests testext._format_command
which does not include nested commands at deeper levels (nested=full
). For full nested commands, it is called several times byClickDirective._generate_nodes
.So I extended the existing full test case with the
:commands:
option.If there is a better way to test string formatting of nested=full, or if you prefer to keep the existing full test unchanged and add a separate one with commands filtering, I am happy to change that.