documentiation cleanup

41e8cd1a · Marco Mariani · 50f2cfaf · 41e8cd1a · 41e8cd1a · 41e8cd1a
Commit 41e8cd1a authored May 03, 2013 by Marco Mariani
6 changed files
--- a/documentation/source/slapos.usage.rst
+++ b/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`
+* 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``.
+* Most commands take a configuration file parameter, provided as ``--cfg /path/to/file.cfg``.
  If no such argument is provided:
-   * "node" commands read configuration from :file:`/etc/opt/slapos/slapos.cfg`, or the path referenced by the
+  * "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,91 +43,92 @@ 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.
+* Request a wordpress instance named "mybeautifulinstance" on Node named "COMP-12345"::
-Examples:
- * Request a wordpress instance named "mybeautifulinstance" on Node named "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
+..
-~~~~~~~~~~~~~
+  search
-Note: Not yet implemented.
+  ~~~~~~
-Usage:
+  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
+..
-~~~~~~~~~~~~~~~~~
+  autosupply
-Note: Not yet implemented.
+  ~~~~~~~~~~
-Usage:
+  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
+console
-~~~~~~~~~~~~~~
+~~~~~~~
-Enter in a python console with slap library imported.
 .. program-output:: python slapos help console
-slapos <stop|start|destroy>
+..
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+  <stop|start|destroy>
-Note: Not yet implemented.
+  ~~~~~~~~~~~~~~~~~~~~
-Usage:
+  Note: Not yet implemented.
+  Usage:
    slapos <stop|start|destroy> <instance reference>
-Ask start/stop/destruction of selected instance.
+  Ask start/stop/destruction of selected instance.
-Example:
+  Example:
    * Ask to stop "mywordpressinstance"::
@@ -136,23 +139,19 @@ Example:
 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
+node register
-~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~
-Usage:
-******
 .. 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
+* Register computer named "mycomputer" to vifib::
    $ slapos node register mycomputer
-  * 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 vifib using br0 as primary interface, tap0 as IPv6 interface and different local ipv4 subnet::
    $ slapos node register mycomputer --interface-name br0 --ipv6-interface tap0 \
        --ipv4-local-network 11.0.0.0/16
-  * 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)::
+* 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::
+* 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
+node software
-~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~
-Usage:
-******
 .. program-output:: python slapos help node software
-Run software installation/deletion.
-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
-~~~~~~~~~~~~~~~~~~
+node report
-Usage:
+~~~~~~~~~~~
-******
-::
 .. 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.
+node start|stop|restart|tail|status
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+::
+ usage: slapos node <start|stop|restart|tail|status> [-h] [--cfg CFG] <instance>:[process]
+ 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
-slapos node <start|stop|restart|tail|status>
+Examples
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Usage:
-  slapos node <start|stop|restart|tail|status> <instance>:[process]
-Start/Stop/Restart/Show stdout/stderr of instance and/or process.
+* Start all processes of slappart3::
-Examples:
+    $ slapos node start slappart3:
- * Start all processes of slappart3:
+* Stop only apache in slappart1::
-     slapos node start slappart3:
- * Stop only apache in slappart1:
+    $ slapos node stop slappart1:apache
-     slapos node stop slappart1:apache
- * Show stdout/stderr of mysqld in slappart2:
+* Show stdout/stderr of mysqld in slappart2::
-     slapos node tail slappart2:mysqld
-slapos node supervisorctl
+    $ 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.
+  node log
-Usage:
+  ~~~~~~~~
+  Note: Not yet implemented.
+  Usage:
    slapos node log <software|instance|report>
-Display log.
+  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
--- a/slapos/cli/console.py
+++ b/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.

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

--- a/slapos/cli/slapgrid.py
+++ b/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')

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

--- a/slapos/cli/supervisord.py
+++ b/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')