Seems this is failing tests - will fix.

OK so fixed the failing tests, mostly by changing the expected output.

Now .SH OPTIONS is .SH ACTIONS because that is the title of the parser.

Also, options not in an argument group are put below subcommands. Is that bad?

Thanks.

Thank you for the PR!

See the example resalloc.1 in tests; what I dislike is that the main command options (--connection and --version) are moved to the bottom of the manual page. They are now below all the sub-commands and theirs options, can we keep them first?

Also, the word ACTIONS sort of replaces the Sub-commands header. So we could keep only ACTIONS?

Fixed re global options movement.

ACTIONS comes from the title of the subparser defined when ading the subparsers. Are you suggesting to delete this bit:

        lines = [
            '.SS',
            self._bold('Sub-commands'),
        ]

?

Yes, either keep "Sub-commands", or "ACTIONS". If I understand your change correctly,
the "Sub-commands" header would always follow immediately after the "ACTIONS" header.

I kept the title (here .SH ACTIONS) if the subparsers was instantiated with a title, otherwise defaulting to .SS Sub-commands.

I'll let you decide if you want to make changes to that they are both .SH or .SS and commit that.

I've created a few more commits in this branch you might be interested in too https://github.com/wwood/argparse-manpage/tree/bird_opinions - most are self-contained in single commits if you wanted to take them. Some border more closely align with my opinions though so may not be interesting.

Also note I changed the instantiation of the copr so that the default (without title) was being tested, intentionally.

Thank you, I briefly checked the bird_opinions changes and they look good. I would prefer to have a PR for them, though, and I may have some questions, but nice!

I'm happy enough with my contributions so far, particularly since I've a special use-case for these man pages and don't require the full code base to be functional meaning I'll have to maintain a fork anyway. Still, I'm happy to answer questions - just shoot me an email or tag me here or something.

Thanks.

I've a special use-case for these man pages and don't require the full code base to be functional meaning I'll have to maintain a fork anyway.

Accepted. Thank you anyway!

@wwood, there was some problem I don't yet understand, but your patch was breaking
builds with python3.10+. Would you take a look and reopen this PR please?

I hope I finally understood the hierarchy, so I rather made a bit more changes to make this correct.
Proposal is in #42.