Refactor the extension to use a Sphinx Domain

[mikemckiernan]

• Add optional command index and optional commands-by-group index.
• Optionally, print fully-qualified subcommand name in title.
• Support commands:command role for intersphinx.
• Prefer fully-qualified HREF targets:
  • Use targets like "#blah-sub-commands" as the primary target and move historic targets like "#Sub-commands" to secondary targets.
  • Preserve the older HREF, "#sub-commands", as a secondary target. In the HTML, this becomes a span just below the section element so that bookmarks continue to work even after adopting the update from this commit.

[mikemckiernan]

Optimistically addresses the rest of #32. Might also address #11.

I stared at breaking this into smaller PRs, but the only separation that made sense was the full_subcommand_name and that seemed too small to bother with. Though, I am willing to revisit the idea if it helps.

[mikemckiernan]

The majority of the doc updates are visible at https://sphinx-argparse--34.org.readthedocs.build/en/34/usage.html#printing-fully-qualified-sub-command-headings.

PLMK if you spot some uglies.

[mikemckiernan]

@ashb , just checking if if there's anything I can answer or do to ease the review. PLMK and thanks.

[peeksake]

Bumping this.

[AA-Turner]

Remaining is to resolve sphinx_argparse_conf -- ideally we would add the permitted keys as config values rather than the indirection of a dict.

[mikemckiernan]

Thanks very, very much @AA-Turner for dusting off this PR and improving it. For your comment about confvals rather than the dictionary, is the idea that the conf.py would look like this?

sphinxarg_commands_index = True
sphinxarg_commands_index_in_toctree = True
sphinxarg_full_subcommand_names = True
sphinxarg_commands_by_group_index = True
sphinxarg_commands_by_group_index_in_toctree = True
sphinxarg_commands_by_group_index_file_suffix = "by-service"
sphinxarg_commands_by_group_index_title = "Commands by Service"

I don't have any strong feelings and I trust your judgement. PLMK what you have in mind and I'll see what I can do. Thanks again!

[RobertoRoos]

@AA-Turner , @mikemckiernan , @ashb
I have some time on my hands and would like to contribute to sphinx-argparse some more. I think this would be a great PR to merge before continuing with anything else. Does anybody remember what the current status is? Thanks!

EDIT: I see a rebased branch is already waiting in https://github.com/mikemckiernan/sphinx-argparse/tree/add-domain-rebase

EDIT 2: I'm guessing the latest comment about no dictionaries in conf.py still stands - I'm working on changing that right now.

[RobertoRoos]

Cache file crept into Git here.

[mikemckiernan]

Ouch, that's an ugly! Aside from the typo that I just noticed in the proposed change log update, the change log reflects what I hoped to accomplish.

Thanks for any help that you can provide!

[mikemckiernan]

s/but/by/