Improve visualisation of command hierarchy in headings

[florimondmanca]

Problem statement

Consider a nested CLI, ie one group with one or more nested commands or groups.

Right now the TOC looks like this:

• root
  • subgroup1
  • subcommand1
  • subcommand2
  • ...
  • subcommand3
  • ...

This is nice and clean, as it allows visualizing the

But… In the page content itself, the hierarchy is only represented by heading styles (more or less big/bold text), like this:

root

Usage: ...
Options: ...

subgroup1

Usage: ...
Options:...

subcommand1

Usage: ...
Options: ...

subcommand2

Usage: ...
Options: ...

subcommand3

Usage: ...
Options: ...

When looking at a given section, it is not obvious to know whether a given command belongs to a parent group (and which one) (see subcommand1 and subcommand2), or if it's just a standalone command (see subcommand3).

Besides, permalinks only contain eg /#subcommand2, which again doesn't convey the actual hierarchy.

Suggested solution

• Make headings contain the full command_path, eg ## root subgroup1 subcommand2
• Permalinks should be updated too, eg /#root-subgroup1-subcommand2 (see custom labels)
• TOC entries should not change, as the TOC already conveys the hierarchy just fine.