search

praiskup / argparse-manpage

Automatically build man-pages for your Python project
Apache License 2.0
40 stars 22 forks source link

manpage: Split out options by argument group. #35

Closed wwood closed 3 years ago

wwood commented 3 years ago

Hi again,

Here I introduce some opinion, that the manpage should separate the options by argument group rather than putting them all under the OPTIONS heading. For programs with lots of options it helps to organise them e.g. like https://wwood.github.io/CoverM/coverm-genome.html

Thoughts?

wwood commented 3 years ago

Seems this is failing tests - will fix.

wwood commented 3 years ago

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.

praiskup commented 3 years ago

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?

wwood commented 3 years ago

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'),
        ]

?

praiskup commented 3 years ago

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.

wwood commented 3 years ago

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.

wwood commented 3 years ago

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

praiskup commented 3 years ago

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!

wwood commented 3 years ago

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.

praiskup commented 3 years ago

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!

praiskup commented 2 years ago

@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?

praiskup commented 2 years ago

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