Add manpage-specific output mode #14
Conversation
More of the same changes, just with more recent version of pep8+flake8 Signed-off-by: Zygmunt Krynicki <zygmunt.krynicki@canonical.com>
The metavar is the name of the "value" available for arguments and for some options. Typical example would be --output FILE. FILE is the metavar string. Signed-off-by: Zygmunt Krynicki <zygmunt.krynicki@canonical.com>
==SUPPRESS== is the magic value used by argparse to hide command line options. We should follow the same behavior. Signed-off-by: Zygmunt Krynicki <zygmunt.krynicki@canonical.com>
Signed-off-by: Zygmunt Krynicki <zygmunt.krynicki@canonical.com>
Signed-off-by: Zygmunt Krynicki <zygmunt.krynicki@canonical.com>
The :prog: argument to the .. argparse:: directive allows programmers to override the program name but prog is typically correctly inferred by argparse, and in some situations, it is already provided to argparse explicitly. To keep code DRY, we should not override it without having an explicit value Signed-off-by: Zygmunt Krynicki <zygmunt.krynicki@canonical.com>
Signed-off-by: Zygmunt Krynicki <zygmunt.krynicki@canonical.com>
Signed-off-by: Zygmunt Krynicki <zygmunt.krynicki@canonical.com>
This mode is changing the way the directive is impacting the resulting document. The layout changes to traditional manpage SYNOPSIS, DESCRIPTION, etc sections. Most of the content is expected to be provided either inline in the nested definitions (indented text below .. argparse::) and immediately after that (for sections other than DESCRIPTION). A number of existing sphinxarg features are not supported yet. Specifically none of the @before @after and @replace pseudo-decorators are handled. Some of the new private methods are re-implementations of similar methods from the generic code path but they could not be reused at this time. Signed-off-by: Zygmunt Krynicki <zygmunt.krynicki@canonical.com>
Signed-off-by: Zygmunt Krynicki <zygmunt.krynicki@canonical.com>
Signed-off-by: Zygmunt Krynicki <zygmunt.krynicki@canonical.com>
|
Lot of changes :)
We need to mention in docs how to use this with manpages, or it just works without any changes needed? |
|
No, everything is backwards compatible. I've specifically made sure to make everything new an opt-in experience. |
|
Ok. Will check this tomorrow morning and merge. |
|
I'm still working on this so it's not really complete yet. I'll definitely write more tests and documentation updates. If you want to hold off until that happens that's fine but I believe in early and often approach :-) |
|
No no. No problemo :) I will merge this. But before, want to check how well it works on my other projects that use this extension. |
Add manpage-specific output mode
|
Seems to be working as it was before, with my project docs. So, merged. |
This branch adds a whole new way to generate man pages. It's not fully complete (see commit logs before) but it is a new, optional mode, that has to be explicitly enabled. I've been testing it with PlainBox see https://code.launchpad.net/~zkrynicki/checkbox/manpages/+merge/227535 with promising results.
Some known issues (but equally broken for current generator) are positional argument names not showing up correctly and lack of support for @before, @after and @replace.