search

mkdocs / mkdocs-click

An MkDocs extension to generate documentation for Click command line applications
https://pypi.org/project/mkdocs-click
Apache License 2.0
105 stars 15 forks source link

Specify subcommands #54

Open saroad2 opened 2 years ago

saroad2 commented 2 years ago

Description

When documenting CLI, one can choose to document all the commands in a single file, or to split the documentation to multiple files by subgroups.

Right now, if I want to document only the subcommand I need to specify the subcommand as my command in the block. However, in that way the parent command isn't shown in the command path. This might cause some confusion

Example

consider that I have a group named my_cli and a subcommands my_sub1 and my_sub2 and I want to document only my_sub1.

If I write:

::: mkdocs-click
    :module: app.cli
    :command: my_sub1

The path printed is my_sub1 [OPTIONS] COMMAND and not the entire path my_cli my_sub1 [OPTIONS] COMMAND.

The only way is to write:

::: mkdocs-click
    :module: app.cli
    :command: my_cli

And to document everything in the same file.

The Desired Ability

One should be able to specify which subcommands to display, not just depth. that means that the block should look like:

::: mkdocs-click
    :module: <module>
    :command: <command>
    :subcommands: [<list of subcommands>]
theodu commented 2 years ago

I really support this idea. I experience the same problem. I have one CLI main group and different sub groups sub_group1, sub_group2 etc. Each sub groups have different commands. I would like to reference every sub_group in a different page, and maybe even every command in a different page. But I cant because otherwise I won't have the full command path. This subcommand feature would be very usefull to split its CLI documentation into several pages while keeping the full path. And this should still be possible if we have several group nesting.

Thank you in advance!

saroad2 commented 2 years ago

Hey @ofek ,

I think the main issue here that there must be a way to document a subcommand with full command path.

In that way the user will have more control over how to divide the documentation into files and stuff. Since click doesn't support a way to get the group of a command in its API, one must get the full command path by invoking the group and descend in the group until reaching the subcommand.