Add preliminary manpage for cmdtest.

2 files changed, 91 insertions, 0 deletions

diff --git a/cmdtest.1.in b/cmdtest.1.in
new file mode 100644
index 0000000..f9aea7b
--- /dev/null
+++ b/cmdtest.1.in
@@ -0,0 +1,78 @@
+.\" Copyright 2011 Lars Wirzenius <liw@liw.fi>
+.\" 
+.\" This program is free software: you can redistribute it and/or modify
+.\" it under the terms of the GNU General Public License as published by
+.\" the Free Software Foundation, either version 3 of the License, or
+.\" (at your option) any later version.
+.\" 
+.\" This program is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+.\" GNU General Public License for more details.
+.\" 
+.\" You should have received a copy of the GNU General Public License
+.\" along with this program.  If not, see <http://www.gnu.org/licenses/>.
+.\"
+.TH CMDTEST 1
+.SH NAME
+cmdtest \- blackbox testing of Unix command line tools
+.SH SYNOPSIS
+.SH DESCRIPTION
+.B cmdtest
+tests Unix command line tools,
+preferably non-interactive ones.
+The user writes some tests,
+consisting of the command to run, the input files given to it,
+and the expected output.
+.B cmdtest
+runs the command,
+compares the actual output to the expected output,
+and reports any differences.
+If everything matches,
+then tests pass.
+.SH OPTIONS
+.SH EXAMPLE
+To test that the
+.BR echo (1)
+command outputs the expected string,
+create a file called
+.I echo-tests/hello.script
+containing the following content:
+.IP
+.nf
+#!/bin/sh
+echo hello, world
+.fi
+.PP
+Also create the file
+.I echo-tests/hello.stdout
+containing:
+.IP
+hello, world
+.PP
+Then you can run the tests:
+.IP
+.nf
+$ cmdtest echo-tests
+test 1/1
+1/1 tests OK, 0 failures
+.fi
+.PP
+If you change the stdout file to be something else,
+.B cmdtest
+will report the differences:
+.IP
+.nf
+$ cmdtest echo-tests
+FAIL: hello: stdout diff:
+--- echo-tests/hello.stdout	2011-09-11 19:14:47 +0100
++++ echo-tests/hello.stdout-actual	2011-09-11 19:14:49 +0100
+@@ -1 +1 @@
+-something else
++hello, world
+
+test 1/1
+0/1 tests OK, 1 failures
+.fi
+.SH "SEE ALSO"
+.BR cliapp (5).
diff --git a/setup.py b/setup.py
index f8f3dd6..30bd03d 100644
--- a/setup.py
+++ b/setup.py
@@ -27,6 +27,18 @@ import subprocess
 import cmdtestlib
 
 
+class GenerateManpage(build):
+
+    def run(self):
+        build.run(self)
+        print 'building manpages'
+        for x in ['cmdtest']:
+            with open('%s.1' % x, 'w') as f:
+                subprocess.check_call(['python', x,
+                                       '--generate-manpage=%s.1.in' % x,
+                                       '--output=%s.1' % x], stdout=f)
+
+
 class CleanMore(clean):
 
     def run(self):
@@ -60,6 +72,7 @@ setup(name='cmdtest',
       scripts=['cmdtest'],
       py_modules=['cmdtestlib'],
       cmdclass={
+        'build': GenerateManpage,
         'check': Check,
         'clean': CleanMore,
       },