Add docstring for GPG.gen_key_input().

gnupg/gnupg.py

@@ -701,15 +701,64 @@ class GPG(object):
         return key
 
     def gen_key_input(self, **kwargs):
-        """Generate GnuPG key(s) through batch file key generation.
+        """Generate a batch file for input to :meth:`GPG.gen_key()`.
 
         The GnuPG batch file key generation feature allows unattended key
         generation by creating a file with special syntax and then providing it
-        to:      gpg --gen-key --batch <batch file>
+        to: ``gpg --gen-key --batch``:
+
+            Key-Type: RSA
+            Key-Length: 4096
+            Name-Real: Autogenerated Key
+            Name-Email: %s@%s
+            Expire-Date: 2014-04-01
+            %pubring foo.gpg
+            %secring sec.gpg
+            %commit
+
+            Key-Type: DSA
+            Key-Length: 1024
+            Subkey-Type: ELG-E
+            Subkey-Length: 1024
+            Name-Real: Joe Tester
+            Name-Comment: with stupid passphrase
+            Name-Email: joe@foo.bar
+            Expire-Date: 0
+            Passphrase: abc
+            %pubring foo.pub
+            %secring foo.sec
+            %commit
 
         see http://www.gnupg.org/documentation/manuals/gnupg-devel/Unattended-GPG-key-generation.html#Unattended-GPG-key-generation
         for more details.
+
+        >>> gpg = GPG(gpghome="keys")
+        >>> params = {'name_real':'python-gnupg tester', 'name_email':'test@ing'}
+        >>> key_input = gpg.gen_key_input(**params)
+        >>> result = gpg.gen_key(input)
+        >>> assert result
+
+        :param str name_real: The uid name for the generated key.
+        :param str name_email: The uid email for the generated key. (default:
+            $USERNAME@$HOSTNAME)
+        :param str name_comment: The comment in the uid of the generated key.
+        :param str key_type: One of 'RSA', 'DSA', or 'ELG-E'. (default: 'RSA')
+        :param int key_length: The length in bytes of the new key.
+            (default: 4096)
+        :param str subkey_type: If ``key_type`` is 'RSA', an additional subkey
+            can be generated, and it's type must also be 'RSA'. If ``key_type``
+            is 'DSA', then the only subkey type which can be generated is
+            'ELG-E'.
+        :param int subkey_length: The length in bytes of the new subkey.
+        :type expire: int or str
+        :param expire: If an integer, the number of days before the key will
+            expire; if 0, the key will not expire. Otherwise, this can be given
+            as a string in the form <n>w or <n>m or <n>y, i.e. "5m" would mean
+            that the key will expire in five months, "1w" would expire in one
+            week, and "3y" would expire in three years. (default: "1y")
+        :param str passphrase: The passphrase for the new key.
         """
+
         parms = {}
         for key, val in list(kwargs.items()):
             key = key.replace('_','-').title()
@@ -734,28 +783,6 @@ class GPG(object):
         out += "%commit\n"
         return out
 
-        # Key-Type: RSA
-        # Key-Length: 1024
-        # Name-Real: ISdlink Server on %s
-        # Name-Comment: Created by %s
-        # Name-Email: isdlink@%s
-        # Expire-Date: 0
-        # %commit
-        #
-        #
-        # Key-Type: DSA
-        # Key-Length: 1024
-        # Subkey-Type: ELG-E
-        # Subkey-Length: 1024
-        # Name-Real: Joe Tester
-        # Name-Comment: with stupid passphrase
-        # Name-Email: joe@foo.bar
-        # Expire-Date: 0
-        # Passphrase: abc
-        # %pubring foo.pub
-        # %secring foo.sec
-        # %commit
-
     #
     # ENCRYPTION
     #