Documentation cleanup; provide defaults from argparse, etc.

documentation/source/slapos.usage.rst

@@ -6,7 +6,7 @@ SlapOS command line usage
 Notes:
 ------
 
-* Default SlapOS Master is http://www.slapos.org. It can be changed by altering configuration files or with the ``--master-url``
+* Default SlapOS Master is https://slap.vifib.com. It can be changed by altering configuration files or with the ``--master-url``
   argument for commands that support it.
 
 * Most commands take a configuration file parameter, provided as ``--cfg /path/to/file.cfg``.
@@ -20,7 +20,8 @@ Notes:
 
 
 
-XXX TODO document 'alias' for software_url, software_group?, computer_group?
+..
+  XXX TODO document 'alias' for software_url, software_group?, computer_group?
 
 
 
@@ -59,7 +60,8 @@ Examples
     $ slapos request mykvm kvm --node id=COMP-12345 --configuration \
         nbd-host=debian.nbd.vifib.net nbd-port=1024
 
-XXX Change in slaplib: allow to fetch instance params without changing anything. i.e we should do "slapos request myalreadyrequestedinstance" to fetch connection parameters without erasing previously defined instance parameters.
+..
+  XXX Change in slaplib: allow to fetch instance params without changing anything. i.e we should do "slapos request myalreadyrequestedinstance" to fetch connection parameters without erasing previously defined instance parameters.
 
 
 ..
@@ -93,7 +95,8 @@ remove
 
 Ask Removal of a software from a specific node or group of nodes. Existing instances won't work anymore.
 
-XXX "slapos autounsupply a.k.a slapos cleanup"
+..
+  XXX "slapos autounsupply a.k.a slapos cleanup"
 
 Examples
 
@@ -160,24 +163,14 @@ If login is not provided, asks for user's SlapOS Master account then password.
 
 Node will register itself, if not already done, to the SlapOS Master defined in configuration file, and will generate SlapOS configuration file.
 
-XXX-Cedric should be like this: If desired node name is already taken, will raise an error.
-XXX-Cedric: --master-url-web url will disappear in REST API. Currently, "register" uses SlapOS master web URL to register computer, so it needs the web URL (like http://www.slapos.org)
+..
+  XXX-Cedric should be like this: If desired node name is already taken, will raise an error.
+  XXX-Cedric: --master-url-web url will disappear in REST API. Currently, "register" uses SlapOS master web URL to register computer, so it needs the web URL (like http://www.slapos.org)
 
 If Node is already registered (slapos.cfg and certificate already present), issues a warning, backups original configuration and creates new one.
 
-XXX-Cedric should check for IPv6 in selected interface
-
-
-Parameters:
-***********
---login LOGIN                  Your SlapOS Master login. If not provided, asks it interactively.
---password PASSWORD            Your SlapOS Master password. If not provided, asks it interactively. NOTE: giving password as parameter should be avoided for security reasons.
---interface-name INTERFACE     Use interface as primary interface. IP of Partitions will be added to it. Defaults to "eth0".
---master-url URL               URL of SlapOS Master REST API. defaults to "https://slap.vifib.com".
---master-url-web URL           URL of SlapOS Master web access. defaults to "https://www.vifib.com".
---partition-number NUMBER      Number of partitions that will have your SlapOS Node. defaults to "10".
---ipv4-local-network NETWORK   Subnetwork used to assign local IPv4 addresses. It should be a not used network in order to avoid conflicts. defaults to 10.0.0.0/16.
--t, --create-tap                   Will trigger creation of one virtual "tap" interface per Partition and attach it to primary interface. Requires primary interface to be a bridge. defaults to false. Needed to host virtual machines.
+..
+  XXX-Cedric should check for IPv6 in selected interface
 
 
 Notes:
@@ -217,7 +210,7 @@ node software
 Return values:
 **************
 
-(Among other standard Python return values)
+(among other standard Python return values)
 
 * 0     Everything went fine
 * 1     At least one software was not correctly installed.
@@ -232,7 +225,7 @@ node instance
 Return values:
 **************
 
-(Among other standard Python return values)
+(among other standard Python return values)
 
 * 0    Everything went fine
 * 1    At least one instance was not correctly processed.
@@ -250,7 +243,7 @@ Run instance reports and garbage collection.
 Return values:
 **************
 
-(Among other standard Python return values)
+(among other standard Python return values)
 
 * 0     Everything went fine
 * 1     At least one instance hasn't correctly been processed.
@@ -266,9 +259,10 @@ node start|stop|restart|tail|status
  Start/Stop/Restart/Show stdout/stderr of instance and/or process.
 
  optional arguments:
-   -h, --help            show this help message and exit
-   --cfg CFG             SlapOS configuration file - defaults to
-                             $SLAPOS_CONFIGURATION or /etc/opt/slapos/slapos.cfg
+  -h, --help       show this help message and exit
+  --cfg CFG        SlapOS configuration file (default: $SLAPOS_CONFIGURATION
+                   or /etc/opt/slapos/slapos.cfg)
+
 
 Examples
 

slapos/cli/config.py

@@ -22,9 +22,10 @@ class ConfigCommand(Command):
 
     def get_parser(self, prog_name):
         ap = super(ConfigCommand, self).get_parser(prog_name)
-        ap.add_argument('--cfg', help='SlapOS configuration file - ' +
-                                      'defaults to $%s ' % self.default_config_var +
-                                      'or %s' % self.default_config_path)
+        ap.add_argument('--cfg',
+                        help='SlapOS configuration file'
+                             ' (default: $%s or %s)' %
+                                (self.default_config_var, self.default_config_path))
         return ap
 
     def _get_config(self, cfg_path, required=False):

slapos/cli/entry.py

@@ -72,7 +72,7 @@ class SlapOSApp(cliff.app.App):
             '--log-file', '--logfile', '--log_file',
             action='store',
             default=None,
-            help='Specify a file to log output. Only console by default.',
+            help='Specify a file to log output (default: console only)',
         )
 
         # always show tracebacks on errors

slapos/cli/format.py

@@ -19,12 +19,10 @@ class FormatCommand(ConfigCommand):
         ap = super(FormatCommand, self).get_parser(prog_name)
 
         ap.add_argument('-x', '--computer_xml',
-                        help="Path to file with computer's XML. If does not exists, will be created",
-                        default=None)
+                        help="Path to file with computer's XML. If does not exists, will be created")
 
         ap.add_argument('--computer_json',
-                        help="Path to a JSON version of the computer's XML (for development only).",
-                        default=None)
+                        help="Path to a JSON version of the computer's XML (for development only)")
 
         ap.add_argument('-i', '--input_definition_file',
                         help="Path to file to read definition of computer instead of "
@@ -36,23 +34,29 @@ class FormatCommand(ConfigCommand):
                         help="Path to file to write definition of computer from "
                         "declaration.")
 
-        ap.add_argument('-n', '--dry_run',
-                        help="Don't actually do anything.",
-                        default=False,
-                        action="store_true")
-
         ap.add_argument('--alter_user',
                         choices=['True', 'False'],
-                        help="Shall slapformat alter user database [default: True]")
+                        default='True',
+                        help='Shall slapformat alter user database'
+                             ' (default: %(default)s)')
 
         ap.add_argument('--alter_network',
                         choices=['True', 'False'],
-                        help="Shall slapformat alter network configuration [default: True]")
+                        default='True',
+                        help='Shall slapformat alter network configuration'
+                             ' (default: %(default)s)')
 
         ap.add_argument('--now',
-                        help="Launch slapformat without delay",
                         default=False,
-                        action="store_true")
+                        action="store_true",
+                        help='Launch slapformat without delay'
+                             ' (default: %(default)s)')
+
+        ap.add_argument('-n', '--dry_run',
+                        default=False,
+                        action="store_true",
+                        help="Don't actually do anything"
+                             " (default: %(default)s)")
 
         return ap
 

slapos/cli/register.py

@@ -21,48 +21,60 @@ class RegisterCommand(Command):
                         help='Name of the node')
 
         ap.add_argument('--interface-name',
-                        help='Interface name to access internet',
-                        default='eth0')
+                        default='eth0',
+                        help='Primary network interface. IP of Partitions '
+                             'will be added to it'
+                             ' (default: %(default)s)')
 
         ap.add_argument('--master-url',
-                        help='URL of SlapOS master',
-                        default='https://slap.vifib.com')
+                        default='https://slap.vifib.com',
+                        help='URL of SlapOS Master REST API'
+                             ' (default: %(default)s)')
 
         ap.add_argument('--master-url-web',
-                        help='URL of SlapOS Master webservice to register certificates',
-                        default='https://www.slapos.org')
+                        default='https://www.slapos.org',
+                        help='URL of SlapOS Master webservice to register certificates'
+                             ' (default: %(default)s)')
 
         ap.add_argument('--partition-number',
-                        help='Number of partition on computer',
-                        default='10',
-                        type=int)
+                        default=10,
+                        type=int,
+                        help='Number of partitions to create in the SlapOS Node'
+                             ' (default: %(default)s)')
 
         ap.add_argument('--ipv4-local-network',
-                        help='Base of ipv4 local network',
-                        default='10.0.0.0/16')
+                        default='10.0.0.0/16',
+                        help='Subnetwork used to assign local IPv4 addresses. '
+                             'It should be a not used network in order to avoid conflicts'
+                             ' (default: %(default)s)')
 
         ap.add_argument('--ipv6-interface',
-                        help='Interface name to get ipv6',
-                        default='')
+                        default='',
+                        help='Interface name to get ipv6')
 
         ap.add_argument('--login',
-                        help='User login on SlapOS Master webservice')
+                        help="Your SlapOS Master login. If not provided, "
+                             "asks it interactively, then password.")
 
         ap.add_argument('--password',
-                        help='User password on SlapOs Master webservice')
+                        help='Your SlapOS Master password. If not provided, '
+                             'asks it interactively. NOTE: giving password as parameter '
+                             'should be avoided for security reasons.')
 
         ap.add_argument('-t', '--create-tap',
+                        default=False,
+                        action='store_true',
                         help='Will trigger creation of one virtual "tap" interface per '
                              'Partition and attach it to primary interface. Requires '
-                             'primary interface to be a bridge. defaults to false. '
-                             'Needed to host virtual machines.',
-                        default=False,
-                        action='store_true')
+                             'primary interface to be a bridge. '
+                             'Needed to host virtual machines'
+                             ' (default: %(default)s)')
 
         ap.add_argument('-n', '--dry-run',
-                        help='Simulate the execution steps',
                         default=False,
-                        action='store_true')
+                        action='store_true',
+                        help='Simulate the execution steps'
+                             ' (default: %(default)s)')
 
         return ap
 

slapos/cli/slapgrid.py

@@ -34,7 +34,7 @@ class SlapgridCommand(ConfigCommand):
                         help='The socket supervisor will use.')
         ap.add_argument('--supervisord-configuration-path',
                         help='The location where supervisord configuration will be stored.')
-        ap.add_argument('--buildout', default=None,
+        ap.add_argument('--buildout',
                         help='Location of buildout binary.')
         ap.add_argument('--pidfile',
                         help='The location where pidfile will be created. '
@@ -50,11 +50,16 @@ class SlapgridCommand(ConfigCommand):
                         help='Root certificate of SlapOS master key.')
         ap.add_argument('--certificate_repository_path',
                         help='Path to directory where downloaded certificates would be stored.')
-        ap.add_argument('--maximum-periodicity', type=int, default=None,
+        ap.add_argument('--maximum-periodicity',
+                        type=int,
                         help='Periodicity at which buildout should be run in instance.')
-        ap.add_argument('--promise-timeout', type=int, default=3,
-                        help='Promise timeout in seconds.')
-        ap.add_argument('--now', action='store_true',
+        ap.add_argument('--promise-timeout',
+                        default=3,
+                        type=int,
+                        help='Promise timeout in seconds'
+                             ' (default: %(default)s)')
+        ap.add_argument('--now',
+                        action='store_true',
                         help='Launch slapgrid without delay. Default behavior.')
         return ap
 

slapos/cli/supply.py

@@ -20,7 +20,7 @@ class SupplyCommand(ClientConfigCommand):
                         help='Your software url')
 
         ap.add_argument('node',
-                        help="Target node")
+                        help='Target node')
 
         return ap