Merge lp:~thumper/juju-core/man-page into lp:~juju/juju-core/trunk

[Tim Penhey]

Add a python script to generate the man page.

To generate a man page locally, first build and install juju (as the python
script calls juju to get the information), then run
  ./scripts/generate-docs.py man

This will create a local juju.1 file. You can use man to look at this by:
  man ./juju.1

To make the gzipped one installed in the right place:
  ./scripts/generate-docs.py man -o - | gzip | sudo tee /usr/share/man/man1/juju.1.gz > /dev/null

There is probably an easier way, but I couldn't figure it out, and gave up looking.

https://codereview.appspot.com/8300043/

[Tim Penhey (thumper)]

Reviewers: mp+156728_code.launchpad.net,

Message:
Please take a look.

Description:
Add a python script to generate the man page.

To generate a man page locally, first build and install juju (as the
python
script calls juju to get the information), then run
   ./scripts/generate-docs.py man

This will create a local juju.1 file. You can use man to look at this
by:
   man ./juju.1

To make the gzipped one installed in the right place:
   ./scripts/generate-docs.py man -o - | gzip | sudo tee
/usr/share/man/man1/juju.1.gz > /dev/null

There is probably an easier way, but I couldn't figure it out, and gave
up looking.

https://code.launchpad.net/~thumper/juju-core/man-page/+merge/156728

(do not edit description out of merge proposal)

Please review this at https://codereview.appspot.com/8300043/

Affected files:
   A [revision details]
   A scripts/generate-docs.py
   A scripts/jujuman.py
   M version/current_test.go
   M version/version.go

[Tim Penhey (thumper)]

Please take a look.

https://codereview.appspot.com/8300043/

[Dimiter Naydenov (dimitern)]

LGTM, nice!

Please link it to lp:1160097, as Dave suggests.

https://codereview.appspot.com/8300043/

[Tim Penhey (thumper)]

*** Submitted:

Add a python script to generate the man page.

To generate a man page locally, first build and install juju (as the
python
script calls juju to get the information), then run
   ./scripts/generate-docs.py man

This will create a local juju.1 file. You can use man to look at this
by:
   man ./juju.1

To make the gzipped one installed in the right place:
   ./scripts/generate-docs.py man -o - | gzip | sudo tee
/usr/share/man/man1/juju.1.gz > /dev/null

There is probably an easier way, but I couldn't figure it out, and gave
up looking.

R=
CC=
https://codereview.appspot.com/8300043

https://codereview.appspot.com/8300043/

=== added file 'scripts/generate-docs.py'
--- scripts/generate-docs.py	1970-01-01 00:00:00 +0000
+++ scripts/generate-docs.py	2013-04-03 03:09:22 +0000
@@ -0,0 +1,64 @@
+#!/usr/bin/env python
+
+# Copyright 2013 Canonical Ltd.
+
+import os
+import sys
+from optparse import OptionParser
+
+from jujuman import JujuMan
+
+
+GENERATORS = {
+    'man': JujuMan
+}
+
+# Insert the directory that this module is in into the python path.
+sys.path.insert(0, (os.path.dirname(__file__)))
+
+def main(argv):
+    parser = OptionParser(usage="""%prog [options] OUTPUT_FORMAT
+
+Available OUTPUT_FORMAT:
+
+    man              man page
+
+And that is all for now.""")
+
+    parser.add_option("-s", "--show-filename",
+                      action="store_true", dest="show_filename", default=False,
+                      help="print default filename on stdout")
+
+    parser.add_option("-o", "--output", dest="filename", metavar="FILE",
+                      help="write output to FILE")
+
+    (options, args) = parser.parse_args(argv)
+
+    if len(args) != 2:
+        parser.print_help()
+        sys.exit(1)
+
+    try:
+        doc_generator = GENERATORS[args[1]]()
+    except KeyError as e:
+        sys.stderr.write("Unknown documentation generator %r\n" % e.message)
+        sys.exit(1)
+
+    if options.filename:
+        outfilename = options.filename
+    else:
+        outfilename = doc_generator.get_filename(options)
+
+    if outfilename == "-":
+        outfile = sys.stdout
+    else:
+        outfile = open(outfilename, "w")
+    if options.show_filename and (outfilename != "-"):
+        sys.stdout.write(outfilename)
+        sys.stdout.write('\n')
+
+    doc_generator.write_documentation(options, outfile)
+
+
+if __name__ == "__main__":
+    main(sys.argv)

=== added file 'scripts/jujuman.py'
--- scripts/jujuman.py	1970-01-01 00:00:00 +0000
+++ scripts/jujuman.py	2013-04-03 03:09:22 +0000
@@ -0,0 +1,160 @@
+"""Functions for generating the manpage using the juju command."""
+
+import subprocess
+import textwrap
+import time
+
+
+class JujuMan(object):
+
+    def __init__(self):
+        self.version = self._version()
+
+    def get_filename(self, options):
+        """Provides name of manpage"""
+        return 'juju.1'
+
+    def run_juju(self, *args):
+        cmd = ['juju'] + list(args)
+        return subprocess.check_output(cmd).strip()
+
+    def _version(self):
+        juju_version = self.run_juju('version')
+        return juju_version.split('-')[0]
+
+    def commands(self):
+        commands = self.run_juju('help', 'commands')
+        result = []
+        for line in commands.split('\n'):
+            name, short_help = line.split(' ', 1)
+            if 'alias for' in short_help:
+                continue
+            result.append((name, short_help.strip()))
+        return result
+
+    def write_documentation(self, options, outfile):
+        """Assembles a man page"""
+        t = time.time()
+        tt = time.gmtime(t)
+        params = {
+            "cmd": "juju",
+            "datestamp": time.strftime("%Y-%m-%d",tt),
+            "timestamp": time.strftime("%Y-%m-%d %H:%M:%S +0000",tt),
+            "version": self.version,
+            }
+        outfile.write(man_preamble % params)
+        outfile.write(man_escape(man_head % params))
+        outfile.write(man_escape(self.getcommand_list(params)))
+        outfile.write("".join(environment_variables()))
+        outfile.write(man_escape(man_foot % params))
+
+    def getcommand_list(self, params):
+        """Builds summary help for command names in manpage format"""
+        output = '.SH "COMMAND OVERVIEW"\n'
+        for cmd_name, short_help in self.commands():
+            tmp = '.TP\n.B "%s %s"\n%s\n' % (params['cmd'], cmd_name, short_help)
+            output = output + tmp
+        return output
+
+
+ENVIRONMENT = (
+    ('JUJU_ENV', textwrap.dedent("""\
+        Provides a way for the shell environment to specify the current Juju
+        environment to use.  If the environment is specified explicitly using
+        -e ENV, this takes precedence.
+        """)),
+    ('JUJU_HOME', textwrap.dedent("""\
+        Overrides the default Juju configuration directory of ~/.juju.
+        """)),
+    ('AWS_ACCESS_KEY_ID', textwrap.dedent("""\
+        The access-key for your AWS account.
+        """)),
+    ('AWS_SECRET_ACCESS_KEY', textwrap.dedent("""\
+        The secret-key for your AWS account.
+        """)),
+    ('OS_USERNAME', textwrap.dedent("""\
+        Your openstack username.
+        """)),
+    ('OS_PASSWORD', textwrap.dedent("""\
+        Your openstack password.
+        """)),
+    ('OS_TENANT_NAME', textwrap.dedent("""\
+        Your openstack tenant name.
+        """)),
+    ('OS_REGION_NAME', textwrap.dedent("""\
+        Your openstack region name.
+        """)),
+)
+
+def man_escape(string):
+    """Escapes strings for man page compatibility"""
+    result = string.replace("\\","\\\\")
+    result = result.replace("`","\\'")
+    result = result.replace("'","\\*(Aq")
+    result = result.replace("-","\\-")
+    return result
+
+
+def environment_variables():
+    yield ".SH \"ENVIRONMENT\"\n"
+
+    for k, desc in ENVIRONMENT:
+        yield ".TP\n"
+        yield ".I \"%s\"\n" % k
+        yield man_escape(desc) + "\n"
+
+
+man_preamble = """\
+.\\\"Man page for Juju (%(cmd)s)
+.\\\"
+.\\\" Large parts of this file are autogenerated from the output of
+.\\\"     \"%(cmd)s help commands\"
+.\\\"     \"%(cmd)s help <cmd>\"
+.\\\"
+.\\\" Generation time: %(timestamp)s
+.\\\"
+
+.ie \\n(.g .ds Aq \\(aq
+.el .ds Aq '
+"""
+
+man_head = """\
+.TH %(cmd)s 1 "%(datestamp)s" "%(version)s" "Juju"
+.SH "NAME"
+%(cmd)s - Juju -- devops distilled
+.SH "SYNOPSIS"
+.B "%(cmd)s"
+.I "command"
+[
+.I "command_options"
+]
+.br
+.B "%(cmd)s"
+.B "help"
+.br
+.B "%(cmd)s"
+.B "help"
+.I "command"
+.SH "DESCRIPTION"
+
+Juju provides easy, intelligent service orchestration on top of environments
+such as OpenStack, Amazon AWS, or bare metal.
+"""
+
+man_foot = """\
+.SH "FILES"
+.TP
+.I "~/.juju/environments.yaml"
+This is the Juju config file, which you can use to specify multiple
+environments in which to deploy.
+
+A config file can be created using
+.B juju init -w
+which you can then edit to provide the secret keys, or use environment
+variables to provide the secret values.
+
+.SH "SEE ALSO"
+.UR https://juju.ubuntu.com/
+.BR https://juju.ubuntu.com/
+"""
+