documentiation cleanup

documentation/source/slapos.usage.rst

@@ -5,23 +5,21 @@ SlapOS command line usage
 
 Notes:
 ------
- * Default SlapOS Master is http://www.vifib.net. It can be changed by altering configuration files or with the `--master-url`
-   argument for commands that support it.
 
- * Most commands (except node register) take a configuration file parameter, provided as ``--cfg /path/to/file.cfg``.
+* Default SlapOS Master is http://www.vifib.net. It can be changed by altering configuration files or with the ``--master-url``
+  argument for commands that support it.
 
-   If no such argument is provided:
-   
-   * "node" commands read configuration from :file:`/etc/opt/slapos/slapos.cfg`, or the path referenced by the
-     ``SLAPOS_CONFIGURATION`` environment variable.
+* Most commands take a configuration file parameter, provided as ``--cfg /path/to/file.cfg``.
 
-   * likewise, "client" commands (request, supply...) use :file:`~/.slapos/slapos.cfg`, or the ``SLAPOS_CLIENT_CONFIGURATION`` variable.
+  If no such argument is provided:
+  
+  * "node" commands read configuration from :file:`/etc/opt/slapos/slapos.cfg`, or the file referenced by the
+    ``SLAPOS_CONFIGURATION`` environment variable.
 
+  * likewise, "client" commands (request, supply...) use :file:`~/.slapos/slapos.cfg`, or the ``SLAPOS_CLIENT_CONFIGURATION`` variable.
 
 
 
-XXX the SLAPOS_CONFIGURATION thing is repeated below for each command
-    we can remove it with :ellipsis:
 XXX TODO document 'alias' for software_url, software_group?, computer_group?
 
 
@@ -29,11 +27,15 @@ XXX TODO document 'alias' for software_url, software_group?, computer_group?
 Common options
 --------------
 
-By itself, the ``slapos`` command lists all the available sub-commands and common options.
+Without arguments, the ``slapos`` program lists all the available commands and common options.
 
 .. program-output:: python slapos
 
 
+The ``-q`` and ``-v`` options control the verbosity of console output (``-v``: DEBUG, default: INFO, ``-q``: WARNING).
+
+Output to a logfile is not affected, and is the same as ``-v``.
+
 
 
 SlapOS Client commands
@@ -41,118 +43,115 @@ SlapOS Client commands
 
 These commands are used by clients (as human beings or programs) to manage their own instances.
 
-slapos request
-~~~~~~~~~~~~~~
+request
+~~~~~~~
 
 .. program-output:: python slapos help request
 
+Examples
 
-Request an instance and get status and parameters of instance.
-
-Examples:
- * Request a wordpress instance named "mybeautifulinstance" on Node named "COMP-12345"::
+* Request a wordpress instance named "mybeautifulinstance" on Node named "COMP-12345"::
 
-     $ slapos request mybeautifulinstance wordpress --node id=COMP-12345
+    $ slapos request mybeautifulinstance wordpress --node id=COMP-12345
 
- * Request a kvm instance named "mykvm" on Node named "COMP-12345", specifying nbd-host and nbd-ip parameters::
+* Request a kvm instance named "mykvm" on Node named "COMP-12345", specifying nbd-host and nbd-ip parameters::
 
-     $ slapos request mykvm kvm --node id=COMP-12345 --configuration nbd-host=debian.nbd.vifib.org nbd-port=1024
+    $ slapos request mykvm kvm --node id=COMP-12345 --configuration \
+        nbd-host=debian.nbd.vifib.org 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.
 
 
-slapos search
-~~~~~~~~~~~~~
-Note: Not yet implemented.
-Usage:
-  slapos search <search parameters ex. computer region, instance reference, source_section, etc.>
+..
+  search
+  ~~~~~~
+  Note: Not yet implemented.
+  Usage:
+    slapos search <search parameters ex. computer region, instance reference, source_section, etc.>
+  
+  Returns visible instances matching search parameters.
 
-Returns visible instances matching search parameters.
 
-
-slapos supply
-~~~~~~~~~~~~~
+supply
+~~~~~~
 
 .. program-output:: python slapos help supply
 
 Ask installation of a software on a specific node or group of nodes. Nodes will then be ready to accept instances of specified software.
 
-Examples:
+Examples
 
- * Ask installation of wordpress Software Release on COMP-12345::
+* Ask installation of wordpress Software Release on COMP-12345::
 
     $ slapos supply wordpress COMP-12345
 
 
-slapos remove
-~~~~~~~~~~~~~
+remove
+~~~~~~
 
 .. program-output:: python slapos help remove
 
-Ask Removal of a software on a specific node or group of nodes. Existing instances won't work anymore.
+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"
 
-Examples:
+Examples
 
- * Ask installation of wordpress Software Release on COMP-12345::
+* Ask installation of wordpress Software Release on COMP-12345::
 
     $ slapos supply wordpress COMP-12345
 
 
-slapos autosupply
-~~~~~~~~~~~~~~~~~
-Note: Not yet implemented.
-Usage:
-  slapos autosupply <software | software_group> <computer_guid | computer_group>
+..
+  autosupply
+  ~~~~~~~~~~
+  Note: Not yet implemented.
+  Usage:
+    slapos autosupply <software | software_group> <computer_guid | computer_group>
+  
+  Like "slapos suppply", but on-demand. Software will be (re)installed only when at least one instance of this software is requested. When no instance of this software is deployed on the node, it will be uninstalled.
 
-Like "slapos suppply", but on-demand. Software will be (re)installed only when at least one instance of this software is requested. When no instance of this software is deployed on the node, it will be uninstalled.
 
-
-slapos console
-~~~~~~~~~~~~~~
-
-Enter in a python console with slap library imported.
+console
+~~~~~~~
 
 .. program-output:: python slapos help console
 
 
 
-slapos <stop|start|destroy>
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Note: Not yet implemented.
-Usage:
-  slapos <stop|start|destroy> <instance reference>
-
-Ask start/stop/destruction of selected instance.
-
-Example:
-
-  * Ask to stop "mywordpressinstance"::
-
-      $ slapos stop mywordpressinstance
+..
+  <stop|start|destroy>
+  ~~~~~~~~~~~~~~~~~~~~
+  Note: Not yet implemented.
+  Usage:
+    slapos <stop|start|destroy> <instance reference>
+  
+  Ask start/stop/destruction of selected instance.
+  
+  Example:
+  
+    * Ask to stop "mywordpressinstance"::
+  
+        $ slapos stop mywordpressinstance
 
 
 
 SlapOS Node commands
 --------------------
 
-This kind of commands is used to control the current SlapOS Node. These commands are only useful for administrators of Nodes.
+This group of commands is used to control the current SlapOS Node. They are only useful to Node administrators.
 
-slapos node
-~~~~~~~~~~~
+node, node status
+~~~~~~~~~~~~~~~~~
 
-This is an alias for ``node supervisorctl status``.
+These are aliases for ``node supervisorctl status``.
 It displays the status of the node, also running the supervisor daemon if needed.
 
-XXX Temporary note: equivalent of old slapgrid-supervisord + slapgrid-supervisorctl.
+.. program-output:: python slapos help node supervisorctl status
 
-.. program-output:: python slapos help node
 
-
-slapos node register
-~~~~~~~~~~~~~~~~~~~~
-Usage:
-******
+node register
+~~~~~~~~~~~~~
 
 .. program-output:: python slapos help node register
 
@@ -179,150 +178,176 @@ Parameters:
 --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.
--n, --dry-run                      Don't touch to anything in the filesystem. Used to debug.
 
 
 Notes:
 ******
-  * "IPv6 interface" and "create tap" won't be put at all in the SlapOS Node configuration file if not explicitly written.
 
-Examples:
-*********
+* "IPv6 interface" and "create tap" won't be put at all in the SlapOS Node configuration file if not explicitly written.
 
-  * Register computer named "mycomputer" to vifib::
+Examples
 
-      $ slapos node register mycomputer
+* Register computer named "mycomputer" to vifib::
 
-  * Register computer named "mycomputer" to vifib using br0 as primary interface, tap0 as IPv6 interface and different local ipv4 subnet::
+    $ slapos node register mycomputer
 
-      $ slapos node register mycomputer --interface-name br0 --ipv6-interface tap0 \
-            --ipv4-local-network 11.0.0.0/16
+* Register computer named "mycomputer" to vifib using br0 as primary interface, tap0 as IPv6 interface and different local ipv4 subnet::
 
-  * Register computer named "mycomputer" to another SlapOS master accessible via https://www.myownslaposmaster.com, and SLAP webservice accessible via https://slap.myownslaposmaster.com (Note that this address should be the "slap" webservice URL, not web URL)::
+    $ slapos node register mycomputer --interface-name br0 --ipv6-interface tap0 \
+        --ipv4-local-network 11.0.0.0/16
 
-      $ slapos node register mycomputer --master-url https://slap.myownslaposmaster.com \
-            --master-url-web https://www.myownslaposmaster.com
+* Register computer named "mycomputer" to another SlapOS master accessible via https://www.myownslaposmaster.com, and SLAP webservice accessible via https://slap.myownslaposmaster.com (Note that this address should be the "slap" webservice URL, not web URL)::
+
+    $ slapos node register mycomputer --master-url https://slap.myownslaposmaster.com \
+        --master-url-web https://www.myownslaposmaster.com
 
 XXX-Cedric : To be implemented
-  * Register computer named "mycomputer" to vifib, and ask to create tap interface to be able to host KVMs::
 
-      $ slapos node register mycomputer --create-tap
+* Register computer named "mycomputer" to vifib, and ask to create tap interface to be able to host KVMs::
 
+    $ slapos node register mycomputer --create-tap
 
-slapos node software
-~~~~~~~~~~~~~~~~~~~~
-Usage:
-******
-
-.. program-output:: python slapos help node software
 
+node software
+~~~~~~~~~~~~~
 
-Run software installation/deletion.
+.. program-output:: python slapos help node software
 
-Temporary note: equivalent of old slapgrid-sr.
-# XXX: only_sr should be named ??? (process-only ?)
-# XXX: add a "-vv", very verbose, option.
 
 Parameters:
 ***********
---logfile LOGFILE              If specified, will log as well output in the file located at FILE.
 --only_sr URL                  Only process one specific Software Release that has been supplied on this Computer. If not supplied: do nothing.
 --all                          Process all Software Releases, even already installed.
---verbose, -v                  Be more verbose.
 
 Return values:
 **************
+
 (Among other standard Python return values)
-0        Everything went fine
-1        At least one software hasn't correctly been installed.
 
+* 0     Everything went fine
+* 1     At least one software hasn't correctly been installed.
 
-slapos node instance
-~~~~~~~~~~~~~~~~~~~~
-Usage:
-******
 
-.. program-output:: python slapos help node instance
+node instance
+~~~~~~~~~~~~~
 
-Temporary note: equivalent of old slapgrid-cp.
+.. program-output:: python slapos help node instance
 
-Run instances deployment.
 
 Parameters:
 ***********
---logfile LOGFILE              If specified, will log as well output in the file located at FILE.
 --only_cp PARTITION            Only process one specific Computer Partition, if possible.
 --all                          Force processing all Computer Partitions.
---verbose, -v                 Be more verbose.
 
 Return values:
 **************
+
 (Among other standard Python return values)
-0        Everything went fine
-1        At least one instance hasn't correctly been processed.
-2        At least one promise has failed.
 
+* 0    Everything went fine
+* 1    At least one instance hasn't correctly been processed.
+* 2    At least one promise has failed.
 
-slapos node report
-~~~~~~~~~~~~~~~~~~
-Usage:
-******
-::
+
+node report
+~~~~~~~~~~~
 
 .. program-output:: python slapos help node report
 
 Run instance reports and garbage collection.
 
-Temporary note: equivalent of old slapgrid-ur.
-
-Parameters:
-***********
---logfile LOGFILE              If specified, will log as well output in the file located at FILE.
---verbose, -v                 Be more verbose.
 
 Return values:
 **************
+
 (Among other standard Python return values)
-0        Everything went fine
-1        At least one instance hasn't correctly been processed.
 
+* 0     Everything went fine
+* 1     At least one instance hasn't correctly been processed.
 
-slapos node <start|stop|restart|tail|status>
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Usage:
-  slapos node <start|stop|restart|tail|status> <instance>:[process]
 
-Start/Stop/Restart/Show stdout/stderr of instance and/or process.
+node start|stop|restart|tail|status
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
 
-Examples:
+ usage: slapos node <start|stop|restart|tail|status> [-h] [--cfg CFG] <instance>:[process]
 
- * Start all processes of slappart3:
-     slapos node start slappart3:
+ Start/Stop/Restart/Show stdout/stderr of instance and/or process.
 
- * Stop only apache in slappart1:
-     slapos node stop slappart1:apache
+ 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
 
- * Show stdout/stderr of mysqld in slappart2:
-     slapos node tail slappart2:mysqld
+Examples
 
-slapos node supervisorctl
-~~~~~~~~~~~~~~~~~~~~~~~~~
+* Start all processes of slappart3::
+
+    $ slapos node start slappart3:
+
+* Stop only apache in slappart1::
+
+    $ slapos node stop slappart1:apache
+
+* Show stdout/stderr of mysqld in slappart2::
+
+    $ slapos node tail slappart2:mysqld
+
+
+
+node supervisorctl
+~~~~~~~~~~~~~~~~~~
 
 .. program-output:: python slapos help node supervisorctl
 
-Enter into supervisor console.
 
-slapos node supervisord
-~~~~~~~~~~~~~~~~~~~~~~~
+node supervisord
+~~~~~~~~~~~~~~~~
 
 .. program-output:: python slapos help node supervisord
 
-Launch, if not already launched, supervisor daemon.
 
-slapos node log
-~~~~~~~~~~~~~~~
-Note: Not yet implemented.
-Usage:
-  slapos node log <software|instance|report>
 
-Display log.
+..
+  node log
+  ~~~~~~~~
+  Note: Not yet implemented.
+  Usage:
+    slapos node log <software|instance|report>
+  
+  Display log.
+
+
+
+
+
+SlapOS Miscellaneous commands
+-----------------------------
+
+cache lookup
+~~~~~~~~~~~~
+
+.. program-output:: python slapos help cache lookup
+
+
+Examples
+
+* See if the wordpress Software Release is available in precompiled format for our distribution::
+
+    $ slapos cache lookup http://git.erp5.org/gitweb/slapos.git/blob_plain/refs/tags/slapos-0.156:/software/kvm/software.cfg
+    Software URL: http://git.erp5.org/gitweb/slapos.git/blob_plain/refs/tags/slapos-0.156:/software/kvm/software.cfg
+    MD5:          4410088e11f370503e9d78db4cfa4ec4
+    -------------
+    Available for: 
+    distribution     |   version    |       id       | compatible?
+    -----------------+--------------+----------------+-------------
+    CentOS           |          6.3 |     Final      | no
+    Fedora           |           17 | Beefy Miracle  | no
+    Ubuntu           |        12.04 |    precise     | yes
+    debian           |        6.0.6 |                | no
+    debian           |          7.0 |                | no
+
+
+
+

slapos/cli/console.py

@@ -8,7 +8,7 @@ from slapos.client import init, do_console, ClientConfig
 
 class ConsoleCommand(ClientConfigCommand):
     """
-    python prompt to interact with slap API
+    python console with slap library imported
 
     You can play with the global "slap" object and
     with the global "request" method.

slapos/cli/request.py

@@ -21,9 +21,7 @@ def parse_option_dict(options):
 
 
 class RequestCommand(ClientConfigCommand):
-    """
-    request an Instance
-    """
+    """request an instance and get status and parameters of instance"""
 
     log = logging.getLogger('request')
 

slapos/cli/slapgrid.py

@@ -55,9 +55,6 @@ class SlapgridCommand(ConfigCommand):
                         help='Promise timeout in seconds.')
         ap.add_argument('--now', action='store_true',
                         help='Launch slapgrid without delay. Default behavior.')
-        ap.add_argument('--all', action='store_true',
-                        help='Launch slapgrid to process all Softare Releases '
-                             'and/or Computer Partitions.')
         return ap
 
     def take_action(self, args):
@@ -83,7 +80,7 @@ class SlapgridCommand(ConfigCommand):
 
 
 class SoftwareCommand(SlapgridCommand):
-    """hook for entry point to process Software Releases"""
+    """run software installation/deletion"""
 
     log = logging.getLogger('software')
 
@@ -92,6 +89,8 @@ class SoftwareCommand(SlapgridCommand):
 
     def get_parser(self, prog_name):
         ap = super(SoftwareCommand, self).get_parser(prog_name)
+        ap.add_argument('--all', action='store_true',
+                        help='Launch slapgrid to process all Softare Releases.')
         ap.add_argument('--only-sr', '--only',
                         help='Force the update of a single software release (can be full URL or MD5 hash), '
                              'even if is already installed. This option will make all other '
@@ -100,7 +99,7 @@ class SoftwareCommand(SlapgridCommand):
 
 
 class InstanceCommand(SlapgridCommand):
-    """hook for entry point to process Computer Partitions"""
+    """run instance deployment"""
 
     log = logging.getLogger('instance')
 
@@ -109,6 +108,8 @@ class InstanceCommand(SlapgridCommand):
 
     def get_parser(self, prog_name):
         ap = super(InstanceCommand, self).get_parser(prog_name)
+        ap.add_argument('--all', action='store_true',
+                        help='Launch slapgrid to process all Computer Partitions.')
         ap.add_argument('--only-cp', '--only',
                         help='Update a single or a list of computer partitions '
                              '(ie.:slappartX, slappartY), '
@@ -117,7 +118,7 @@ class InstanceCommand(SlapgridCommand):
 
 
 class ReportCommand(SlapgridCommand):
-    """hook for entry point to process Usage Reports"""
+    """run instance reports and garbage collection"""
 
     log = logging.getLogger('report')
 

slapos/cli/supervisorctl.py

@@ -11,9 +11,7 @@ import supervisor.supervisorctl
 
 
 class SupervisorctlCommand(ConfigCommand):
-    """
-    manage supervisor processes
-    """
+    """enter into supervisor console, for process management"""
 
     log = logging.getLogger('supervisorctl')
 

slapos/cli/supervisord.py

@@ -8,7 +8,7 @@ from slapos.grid.svcbackend import launchSupervisord
 
 
 class SupervisordCommand(ConfigCommand):
-    """run the supervisor daemon"""
+    """launch, if not already running, supervisor daemon"""
 
     log = logging.getLogger('supervisord')