Nested subcommands improvement

[marekvi95]

Hello, thanks for the plugin, it's an excellent tool for documenting click-based apps.

I would like to ask you for improvement. We are using sphinx-click together with the sphinx.ext.autosectionlabel extension. However, there's a problem with subcommands with the same name. For example, we have two applications that share some of their subcommand names:

  tphost                Application to secure Trust provisioning process of loading application in Un-..
  ├── check-log-owner   Check whether TP Device ID matches the ID in audit log.
  ├── device-help       Command prints help for all devices or optionally only for specified.
  ├── get-cfg-template  Command to generate tphost template of configuration YML file.
  ├── get-counters      Get Provisioning counters from TP device.
  ├── list-tpdevices    Command prints all supported and connected TP devices.
  ├── list-tptargets    Command prints all supported and connected TP targets.
  ├── load              Command to provision target MCU.
  ├── target-help       Command prints help for all targets or optionally only for specified.
  └── verify            Verify audit log integrity and optionally extract certificates.

and

  tpconfig              Application for configuration of trusted device.
  ├── device-help       Command prints help for all devices or optionally only for specified.
  ├── get-cfg-template  Command to generate tphost template of configuration YML file.
  ├── get-counters      Get Provisioning counters from TP device.
  ├── list-tpdevices    Command prints all supported and connected TP devices.
  ├── load              Command to load configuration to the TP device.
  └── seal              Seal the smart card (advancing its lifecycle to PRODUCTION).

The problem is that each subcommand is a label that is not unique. So when we use it together with autosectionlabel we duplicate labels get warnings:

tphost.rst:2: WARNING: duplicate label load, other instance in tpconfig.rst

The solution is to set nested to "none" but it's useless in this case... So would it be possible to somehow add prefixes to labels of subcommands?

Prefix would be really useful for commands with more than one level of nesting, for example this:

  nxpimage                   NXP Image tool.
  ├── ahab                   Group of sub-commands related to AHAB.
  │   ├── export             Generate AHAB Image from YAML/JSON configuration.
  │   ├── get-template       Create template of configuration in YAML format.
  │   └── parse              Parse AHAB Image into YAML configuration and binary images.
  ├── bootable-image         Group of bootable image utilities.
  │   ├── fcb                FCB (Flash Configuration Block) utilities.
  │   │   ├── export         Export FCB Image from YAML/JSON configuration.
  │   │   ├── get-templates  Create template of configurations in YAML format fro all memory types.
  │   │   └── parse          Parse FCB Image into YAML configuration and binary images.
  │   ├── get-templates      Create template of configurations in YAML format from all memory types.
  │   ├── merge              Merge boot image blocks into one bootable image.
  │   └── parse              Parse Bootable Image into YAML configuration and binary images.
...

thanks

[stephenfin]

I think #100 would address this