Build man page tool.

timvideos · Apr 22, 2014 · 4a5c86d · 4a5c86d
1 parent eb803a4
commit 4a5c86d
Show file tree

Hide file tree

Showing 2 changed files with 172 additions and 0 deletions.
diff --git a/build_manpage.py b/build_manpage.py
@@ -0,0 +1,127 @@
+# -*- coding: utf-8 -*-
+
+"""build_manpage command -- Generate man page from setup()"""
+
+import datetime
+from distutils.command.build import build
+from distutils.core import Command
+from distutils.errors import DistutilsOptionError
+import argparse
+
+
+class build_manpage(Command):
+
+    description = 'Generate man page from setup().'
+
+    user_options = [
+        ('output=', 'O', 'output file'),
+        ('parser=', None, 'module path to argparser (e.g. mymod:func'),
+        ]
+
+    def initialize_options(self):
+        self.output = None
+        self.parser = None
+
+    def finalize_options(self):
+        if self.output is None:
+            raise DistutilsOptionError('\'output\' option is required')
+        if self.parser is None:
+            raise DistutilsOptionError('\'parser\' option is required')
+        mod_name, func_name = self.parser.split(':')
+        fromlist = mod_name.split('.')
+        try:
+            mod = __import__(mod_name, fromlist=fromlist)
+            self._parser = getattr(mod, func_name)()
+        except ImportError, err:
+            raise
+        self._parser.formatter = ManPageFormatter()
+        self._parser.formatter.set_parser(self._parser)
+        self.announce('Writing man page %s' % self.output)
+        self._today = datetime.date.today()
+
+    def _markup(self, txt):
+        return txt.replace('-', '\\-')
+
+    def _write_header(self):
+        appname = self.distribution.get_name()
+        ret = []
+        ret.append('.TH %s 1 %s\n' % (self._markup(appname),
+                                      self._today.strftime('%Y\\-%m\\-%d')))
+        description = self.distribution.get_description()
+        if description:
+            name = self._markup('%s - %s' % (self._markup(appname),
+                                             description.splitlines()[0]))
+        else:
+            name = self._markup(appname)
+        ret.append('.SH NAME\n%s\n' % name)
+        synopsis = self._parser.get_usage()
+        if synopsis:
+            synopsis = synopsis.replace('%s ' % appname, '')
+            ret.append('.SH SYNOPSIS\n.B %s\n%s\n' % (self._markup(appname),
+                                                      synopsis))
+        long_desc = self.distribution.get_long_description()
+        if long_desc:
+            ret.append('.SH DESCRIPTION\n%s\n' % self._markup(long_desc))
+        return ''.join(ret)
+
+    def _write_options(self):
+        ret = ['.SH OPTIONS\n']
+        ret.append(self._parser.format_option_help())
+        return ''.join(ret)
+
+    def _write_footer(self):
+        ret = []
+        appname = self.distribution.get_name()
+        author = '%s <%s>' % (self.distribution.get_author(),
+                              self.distribution.get_author_email())
+        ret.append(('.SH AUTHORS\n.B %s\nwas written by %s.\n'
+                    % (self._markup(appname), self._markup(author))))
+        homepage = self.distribution.get_url()
+        ret.append(('.SH DISTRIBUTION\nThe latest version of %s may '
+                    'be downloaded from\n'
+                    '.UR %s\n.UE\n'
+                    % (self._markup(appname), self._markup(homepage),)))
+        return ''.join(ret)
+
+    def run(self):
+        manpage = []
+        manpage.append(self._write_header())
+        manpage.append(self._write_options())
+        manpage.append(self._write_footer())
+        stream = open(self.output, 'w')
+        stream.write(''.join(manpage))
+        stream.close()
+
+
+class ManPageFormatter(argparse.HelpFormatter):
+
+    def __init__(self,
+                 indent_increment=2,
+                 max_help_position=24,
+                 width=None):
+        argparse.HelpFormatter.__init__(
+            self, indent_increment, max_help_position, width)
+
+    def _markup(self, txt):
+        return txt.replace('-', '\\-')
+
+    def format_usage(self, usage):
+        return self._markup(usage)
+
+    def format_heading(self, heading):
+        if self.level == 0:
+            return ''
+        return '.TP\n%s\n' % self._markup(heading.upper())
+
+    def format_option(self, option):
+        result = []
+        opts = self.option_strings[option]
+        result.append('.TP\n.B %s\n' % self._markup(opts))
+        if option.help:
+            help_text = '%s\n' % self._markup(self.expand_default(option))
+            result.append(help_text)
+        return ''.join(result)
+
+
+build.sub_commands.append(('build_manpage', None))
+
diff --git a/dvsource-v4l2-other.1 b/dvsource-v4l2-other.1
@@ -0,0 +1,45 @@
+.\" dvsource-v4l2-other.1 written by Tim Ansell <mithro@mithis.com>
+.TH DVSOURCE-V4L2-OTHER 1 "24 May 2009"
+.SH NAME
+dvsource-v4l2-other \- Video4Linux2 source which supports any input format for DVswitch
+.SH SYNOPSIS
+.HP
+.B dvsource-v4l2-other
+.RI [ OPTIONS ]
+.RB [ \-c
+.IR CARD-NUMBER " | " DEVICE ]
+.HP
+.B dvsource-v4l2-dv
+.RI [ OPTIONS "] [" DEVICE ]
+.SH DESCRIPTION
+.LP
+\fBdvsource-firewire\fR uses \fBdvgrab\fR(1) to stream from a DV
+device (camera or VCR) connected by Firewire.
+.LP
+\fBdvsource-v4l2-dv\fR uses \fBdvgrab\fR(1) to stream from a DV device
+that has a Video4Linux2 driver.  This includes most USB DV cameras if
+you have the uvcvideo driver installed.
+.SH OPTIONS
+\fB\-t\fR, \fB\-\-tally\fR
+.RS
+Print notices of activation and deactivation in the mixer, for use
+with a tally light.  These will take the form "TALLY: on" or "TALLY:
+off".
+.RE
+.TP
+\fB\-h\fR, \fB\-\-host=\fIHOST\fR
+.TP
+\fB\-p\fR, \fB\-\-port=\fIPORT\fR
+.RS
+Specify the network address on which DVswitch is listening.  The host
+address may be specified by name or as an IPv4 or IPv6 literal.
+.RE
+.TP
+\fB\-c\fR, \fB\-\-card=\fICARD-NUMBER\fR
+.RS
+Specify the index of the Firewire card the DV device is connected to.
+.RE
+.SH AUTHOR
+Ben Hutchings <ben@decadent.org.uk>.
+.SH SEE ALSO
+dvgrab(1), /usr/share/doc/dvswitch/README