Description
Great extension. It's used by my team and I have suggestions for some significant revision.
I have an implementation of all the following items, but I'm cataloging them to find out the most approachable way to open PRs and request feedback.
- Add basic HTML tests, inspired by test_build_html.py from the Sphinx project. My goal with this item is to prevent introducing regressions. PR: Add HTML tests to avoid regressions #33.
- Implement the Domain API to enable the following improvements:
- (Kind of a freebie from implementing the domain...) Create domain-specific xref targets like
:command:fancytool install``. These xref targets are valid within the project and can be referenced cross-project with intersphinx. - Add an optional command index of all commands and sub-commands in a docset.
- Add an optional command-by-group index. The proposal here is to add a
:idxgroups:directive so that commands can be grouped in an index. In the proposed tests, I used "ham on a stick" and "spam in a cone" as groups, but IRL, the groups are like "Core Services" and "Common Utilities." - Add a
full_subcommand_nameoption so that when headings are printed for sub-commands, the fully-qualified command name is printed. My opinion is that this helps orient readers for projects that use deeply nested sub-commands.
I made a fake PR in my fork so you can skim the diffs. If you are open to reviewing all the changes at once, that's fine by me, I just fear that could be unnecessarily challenging. I can make one PR for the first issue. I think the next four have to be one PR, though maybe I can make the domain and tests for xrefs into one PR and maybe break the two different indicies into separate PRs.
I'm not 100% sure, but I think that implementing the domain addresses #11. Refer to an example in a test file or some of the tests.
I hope the proposal is compelling. Please let me know whether you are receptive to one "big bang" PR or which smaller ones you'd prefer. If I can clarify anything, please let me know.