build manpages with sphinx
right now, we have this terrible system to build manpages that is based on dealing with the argparse
Python library. it is obscure, doesn't work very well and can't manage to build mutliple manpages cleanly since we ported from optparse
.
maybe it would be better to just generate manapages from the usage
documentation. the following makes a pretty nice manpage:
diff --git a/doc/conf.py b/doc/conf.py
index 3022103..de18650 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -238,7 +238,7 @@
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
- ('index', 'monkeysign', u'Monkeysign Documentation',
+ ('usage', 'monkeysign', u'Monkeysign Documentation',
[u'Antoine Beaupré'], 1)
]
but it lacks the parameters documented in --help
.
borg uses a custom command to generate RST usage files for their main documentation. see their build_usage
command: https://github.com/borgbackup/borg/blob/master/setup.py#L156
we could reuse that to build a usage file that could be included in a hand-maintained documentation. right now it's a horrible mess.