man pages updated (#33307)

sphinx build fixes
doc additions for new modules including thorium

doc/man/salt-api.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH "SALT-API" "1" "February 01, 2016" "2015.8.0" "Salt"
+.TH "SALT-API" "1" "May 17, 2016" "2016.3.0" "Salt"
 .SH NAME
 salt-api \- salt-api Command
 .

doc/man/salt-call.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH "SALT-CALL" "1" "February 01, 2016" "2015.8.0" "Salt"
+.TH "SALT-CALL" "1" "May 17, 2016" "2016.3.0" "Salt"
 .SH NAME
 salt-call \- salt-call Documentation
 .

doc/man/salt-cloud.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH "SALT-CLOUD" "1" "February 01, 2016" "2015.8.0" "Salt"
+.TH "SALT-CLOUD" "1" "May 17, 2016" "2016.3.0" "Salt"
 .SH NAME
 salt-cloud \- Salt Cloud Command
 .
@@ -142,7 +142,7 @@ cloud provider carefully.
 .INDENT 0.0
 .TP
 .B \-u, \-\-update\-bootstrap
-Update salt\-bootstrap to the latest develop version on GitHub.
+Update salt\-bootstrap to the latest stable bootstrap release.
 .UNINDENT
 .INDENT 0.0
 .TP

doc/man/salt-cp.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH "SALT-CP" "1" "February 01, 2016" "2015.8.0" "Salt"
+.TH "SALT-CP" "1" "May 17, 2016" "2016.3.0" "Salt"
 .SH NAME
 salt-cp \- salt-cp Documentation
 .
@@ -109,6 +109,9 @@ Logfile logging log level. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP,
 \fBwarning\fP\&.
 .UNINDENT
 .SS Target Selection
+.sp
+The default matching that Salt utilizes is shell\-style globbing around the
+minion id. See \fI\%https://docs.python.org/2/library/fnmatch.html#module\-fnmatch\fP\&.
 .INDENT 0.0
 .TP
 .B \-E, \-\-pcre

doc/man/salt-key.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH "SALT-KEY" "1" "February 01, 2016" "2015.8.0" "Salt"
+.TH "SALT-KEY" "1" "May 17, 2016" "2016.3.0" "Salt"
 .SH NAME
 salt-key \- salt-key Documentation
 .
@@ -294,10 +294,10 @@ default is 2048.
 .INDENT 0.0
 .TP
 .B \-\-gen\-signature
-Create a signature file of the masters public\-key named
+Create a signature file of the master\(aqs public\-key named
-master_pubkey_signature. The signature can be send to a minion in the
+master_pubkey_signature. The signature can be sent to a minion in the
-masters auth\-reply and enables the minion to verify the masters public\-key
+master\(aqs auth\-reply and enables the minion to verify the master\(aqs public\-key
-cryptographically. This requires a new signing\-key\- pair which can be
+cryptographically. This requires a new signing\-key\-pair which can be
 auto\-created with the \-\-auto\-create parameter.
 .UNINDENT
 .INDENT 0.0

doc/man/salt-master.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH "SALT-MASTER" "1" "February 01, 2016" "2015.8.0" "Salt"
+.TH "SALT-MASTER" "1" "May 17, 2016" "2016.3.0" "Salt"
 .SH NAME
 salt-master \- salt-master Documentation
 .

doc/man/salt-minion.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH "SALT-MINION" "1" "February 01, 2016" "2015.8.0" "Salt"
+.TH "SALT-MINION" "1" "May 17, 2016" "2016.3.0" "Salt"
 .SH NAME
 salt-minion \- salt-minion Documentation
 .

doc/man/salt-proxy.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH "SALT-PROXY" "1" "February 01, 2016" "2015.8.0" "Salt"
+.TH "SALT-PROXY" "1" "May 17, 2016" "2016.3.0" "Salt"
 .SH NAME
 salt-proxy \- salt-proxy Documentation
 .

doc/man/salt-run.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH "SALT-RUN" "1" "February 01, 2016" "2015.8.0" "Salt"
+.TH "SALT-RUN" "1" "May 17, 2016" "2016.3.0" "Salt"
 .SH NAME
 salt-run \- salt-run Documentation
 .

doc/man/salt-ssh.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH "SALT-SSH" "1" "February 01, 2016" "2015.8.0" "Salt"
+.TH "SALT-SSH" "1" "May 17, 2016" "2016.3.0" "Salt"
 .SH NAME
 salt-ssh \- salt-ssh Documentation
 .
@@ -136,52 +136,15 @@ the configuration files for Salt master and minions. The default location
 on most systems is \fB/etc/salt\fP\&.
 .UNINDENT
 .SS Target Selection
+.sp
+The default matching that Salt utilizes is shell\-style globbing around the
+minion id. See \fI\%https://docs.python.org/2/library/fnmatch.html#module\-fnmatch\fP\&.
 .INDENT 0.0
 .TP
 .B \-E, \-\-pcre
 The target expression will be interpreted as a PCRE regular expression
 rather than a shell glob.
 .UNINDENT
-.INDENT 0.0
-.TP
-.B \-L, \-\-list
-The target expression will be interpreted as a comma\-delimited list;
-example: server1.foo.bar,server2.foo.bar,example7.quo.qux
-.UNINDENT
-.INDENT 0.0
-.TP
-.B \-G, \-\-grain
-The target expression matches values returned by the Salt grains system on
-the minions. The target expression is in the format of \(aq<grain value>:<glob
-expression>\(aq; example: \(aqos:Arch*\(aq
-.sp
-This was changed in version 0.9.8 to accept glob expressions instead of
-regular expression. To use regular expression matching with grains, use
-the \-\-grain\-pcre option.
-.UNINDENT
-.INDENT 0.0
-.TP
-.B \-\-grain\-pcre
-The target expression matches values returned by the Salt grains system on
-the minions. The target expression is in the format of \(aq<grain value>:<
-regular expression>\(aq; example: \(aqos:Arch.*\(aq
-.UNINDENT
-.INDENT 0.0
-.TP
-.B \-N, \-\-nodegroup
-Use a predefined compound target defined in the Salt master configuration
-file.
-.UNINDENT
-.INDENT 0.0
-.TP
-.B \-R, \-\-range
-Instead of using shell globs to evaluate the target, use a range expression
-to identify targets. Range expressions look like %cluster.
-.sp
-Using the Range option requires that a range server is set up and the
-location of the range server is referenced in the master configuration
-file.
-.UNINDENT
 .SS Logging Options
 .sp
 Logging options which override any settings defined on the configuration files.

doc/man/salt-syndic.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH "SALT-SYNDIC" "1" "February 01, 2016" "2015.8.0" "Salt"
+.TH "SALT-SYNDIC" "1" "May 17, 2016" "2016.3.0" "Salt"
 .SH NAME
 salt-syndic \- salt-syndic Documentation
 .

doc/man/salt-unity.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH "SALT-UNITY" "1" "February 01, 2016" "2015.8.0" "Salt"
+.TH "SALT-UNITY" "1" "May 17, 2016" "2016.3.0" "Salt"
 .SH NAME
 salt-unity \- salt-unity Command
 .

doc/man/salt.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH "SALT" "1" "February 01, 2016" "2015.8.0" "Salt"
+.TH "SALT" "1" "May 17, 2016" "2016.3.0" "Salt"
 .SH NAME
 salt \- salt
 .
@@ -191,6 +191,9 @@ Logfile logging log level. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP,
 \fBwarning\fP\&.
 .UNINDENT
 .SS Target Selection
+.sp
+The default matching that Salt utilizes is shell\-style globbing around the
+minion id. See \fI\%https://docs.python.org/2/library/fnmatch.html#module\-fnmatch\fP\&.
 .INDENT 0.0
 .TP
 .B \-E, \-\-pcre

doc/man/spm.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH "SPM" "1" "February 01, 2016" "2015.8.0" "Salt"
+.TH "SPM" "1" "May 17, 2016" "2016.3.0" "Salt"
 .SH NAME
 spm \- Salt Package Manager Command
 .

doc/ref/configuration/master.rst

@@ -591,7 +591,7 @@ what you are doing! Transports are explained in :ref:`Salt Transports
     transport: zeromq
 
 ``transport_opts``
--------------
+------------------
 
 Default: ``{}``
 

doc/ref/executors/all/salt.executors.direct_call.rst

@@ -0,0 +1,6 @@
+salt.executors.direct_call module
+=================================
+
+.. automodule:: salt.executors.direct_call
+    :members:
+

doc/ref/executors/all/salt.executors.splay.rst

@@ -0,0 +1,6 @@
+salt.executors.splay module
+===========================
+
+.. automodule:: salt.executors.splay
+    :members:
+

doc/ref/executors/all/salt.executors.sudo.rst

@@ -0,0 +1,6 @@
+salt.executors.sudo module
+==========================
+
+.. automodule:: salt.executors.sudo
+    :members:
+

doc/ref/index.rst

@@ -26,5 +26,6 @@ This section contains a list of the Python modules that are used to extend the v
     ../ref/sdb/all/index
     ../ref/serializers/all/index
     ../ref/states/all/index
+    ../ref/thorium/all/index
     ../ref/tops/all/index
     ../ref/wheel/all/index

doc/ref/modules/all/salt.modules.parallels.rst

@@ -0,0 +1,6 @@
+salt.modules.parallels module
+=============================
+
+.. automodule:: salt.modules.parallels
+    :members:
+

doc/ref/thorium/all/index.rst

@@ -0,0 +1,17 @@
+.. _all-salt.thorium:
+
+====================================
+Full list of builtin thorium modules
+====================================
+
+.. currentmodule:: salt.thorium
+
+.. autosummary::
+    :toctree:
+    :template: autosummary.rst.tmpl
+
+    check
+    file
+    local
+    reg
+    timer

doc/ref/thorium/all/salt.thorium.check.rst

@@ -0,0 +1,6 @@
+salt.thorium.check module
+=========================
+
+.. automodule:: salt.thorium.check
+    :members:
+

doc/ref/thorium/all/salt.thorium.file.rst

@@ -0,0 +1,6 @@
+salt.thorium.file module
+========================
+
+.. automodule:: salt.thorium.file
+    :members:
+

doc/ref/thorium/all/salt.thorium.local.rst

@@ -0,0 +1,6 @@
+salt.thorium.local module
+=========================
+
+.. automodule:: salt.thorium.local
+    :members:
+

doc/ref/thorium/all/salt.thorium.reg.rst

@@ -0,0 +1,6 @@
+salt.thorium.reg module
+=======================
+
+.. automodule:: salt.thorium.reg
+    :members:
+

doc/ref/thorium/all/salt.thorium.timer.rst

@@ -0,0 +1,6 @@
+salt.thorium.timer module
+=========================
+
+.. automodule:: salt.thorium.timer
+    :members:
+

salt/cloud/clouds/dimensiondata.py

@@ -325,10 +325,12 @@ def create(vm_):
 
 
 def create_lb(kwargs=None, call=None):
-    '''
+    r'''
     Create a load-balancer configuration.
     CLI Example:
+
     .. code-block:: bash
+
         salt-cloud -f create_lb dimensiondata \
             name=dev-lb port=80 protocol=http \
             members=w1,w2,w3 algorithm=ROUND_ROBIN
@@ -453,10 +455,14 @@ def ssh_interface(vm_):
 def stop(name, call=None):
     '''
     Stop a VM in DimensionData.
-    name
+
+    name:
         The name of the VM to stop.
+
     CLI Example:
+
     .. code-block:: bash
+
         salt-cloud -a stop vm_name
     '''
     conn = get_conn()
@@ -472,10 +478,14 @@ def stop(name, call=None):
 def start(name, call=None):
     '''
     Stop a VM in DimensionData.
-    name
+
+    :param str name:
         The name of the VM to stop.
+
     CLI Example:
+
     .. code-block:: bash
+
         salt-cloud -a stop vm_name
     '''
 

salt/engines/slack.py

@@ -2,14 +2,15 @@
 '''
 An engine that reads messages from Slack and sends them to the Salt
 event bus.  Alternatively Salt commands can be sent to the Salt master
-via Slack by setting the control paramter to True and using command
+via Slack by setting the control parameter to ``True`` and using command
-prefaced with a !.
+prefaced with a ``!``.
 
 .. versionadded: 2016.3.0
 
-:configuration:
+:configuration: Example configuration
+
+    .. code-block:: yaml
 
-    Example configuration
         engines:
             - slack:
                token: 'xoxb-xxxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxx'

salt/executors/splay.py

@@ -66,20 +66,24 @@ class SplayExecutor(ModuleExecutorBase):
         Splay a salt function call execution time across minions over
         a number of seconds (default: 600)
 
-
+        .. note::
-        NOTE: You *probably* want to use --async here and look up the job results later.
+            You *probably* want to use --async here and look up the job results later.
-              If you're dead set on getting the output from the CLI command, then make
+            If you're dead set on getting the output from the CLI command, then make
-              sure to set the timeout (with the -t flag) to something greater than the
+            sure to set the timeout (with the -t flag) to something greater than the
-              splaytime (max splaytime + time to execute job).
+            splaytime (max splaytime + time to execute job).
-              Otherwise, it's very likely that the cli will time out before the job returns.
+            Otherwise, it's very likely that the cli will time out before the job returns.
-
 
         CLI Example:
-        # With default splaytime
-          salt --async '*' splay.splay pkg.install cowsay version=3.03-8.el6
 
-        # With specified splaytime (5 minutes) and timeout with 10 second buffer
+        .. code-block:: bash
-          salt -t 310 '*' splay.splay 300 pkg.version cowsay
+
+            # With default splaytime
+            salt --async '*' splay.splay pkg.install cowsay version=3.03-8.el6
+
+        .. code-block:: bash
+
+            # With specified splaytime (5 minutes) and timeout with 10 second buffer
+            salt -t 310 '*' splay.splay 300 pkg.version cowsay
         '''
         my_delay = self._calc_splay(__grains__['id'], splaytime=self.splaytime)
         log.debug("Splay is sleeping {0} secs on {1}".format(my_delay, self.fun_name))

salt/modules/bcache.py

@@ -282,10 +282,11 @@ def cache_make(dev, reserved=None, force=False, block_size=None, bucket_size=Non
         salt '*' bcache.cache_make sdb reserved=10% block_size=4096
 
 
-    :param reserved: if dev is a full device, create a partitition table with this size empty.
+    :param reserved: if dev is a full device, create a partition table with this size empty.
-    .. note::
+
-      this increases the amount of reserved space available to SSD garbage collectors,
+        .. note::
-      potentially (vastly) increasing performance
+              this increases the amount of reserved space available to SSD garbage collectors,
+              potentially (vastly) increasing performance
     :param block_size: Block size of the cache; defaults to devices' logical block size
     :param force: Overwrite existing BCache sets
     :param attach: Attach all existing backend devices immediately

salt/modules/chronos.py

@@ -54,7 +54,9 @@ def jobs():
     Return a list of the currently installed job names.
 
     CLI Example:
+
     .. code-block:: bash
+
         salt chronos-minion-id chronos.jobs
     '''
     job_names = _jobs().keys()
@@ -67,7 +69,9 @@ def has_job(name):
     Return whether the given job is currently configured.
 
     CLI Example:
+
     .. code-block:: bash
+
         salt chronos-minion-id chronos.has_job my-job
     '''
     return name in _jobs()
@@ -78,7 +82,9 @@ def job(name):
     Return the current server configuration for the specified job.
 
     CLI Example:
+
     .. code-block:: bash
+
         salt chronos-minion-id chronos.job my-job
     '''
     jobs = _jobs()
@@ -92,7 +98,9 @@ def update_job(name, config):
     Update the specified job with the given configuration.
 
     CLI Example:
+
     .. code-block:: bash
+
         salt chronos-minion-id chronos.update_job my-job '<config yaml>'
     '''
     if 'name' not in config:
@@ -123,7 +131,9 @@ def rm_job(name):
     Remove the specified job from the server.
 
     CLI Example:
+
     .. code-block:: bash
+
         salt chronos-minion-id chronos.rm_job my-job
     '''
     response = salt.utils.http.query(

salt/modules/cmdmod.py

@@ -687,10 +687,10 @@ def run(cmd,
     Note that ``env`` represents the environment variables for the command, and
     should be formatted as a dict, or a YAML string which resolves to a dict.
 
-    :param str cmd: The command to run. ex: 'ls -lart /home'
+    :param str cmd: The command to run. ex: ``ls -lart /home``
 
     :param str cwd: The current working directory to execute the command in,
-      defaults to `/root` (`C:\` in windows)
+      defaults to ``/root`` (``C:\`` in windows)
 
     :param str stdin: A string of standard input can be specified for the
       command to be run using the ``stdin`` parameter. This can be useful in cases

salt/modules/dockercompose.py

@@ -16,10 +16,11 @@ This module allows to deal with docker-compose file in a directory.
 
 This is  a first version only, the following commands are missing at the moment
 but will be built later on if the community is interested in this module:
-  - run
+
-  - logs
+- run
-  - port
+- logs
-  - scale
+- port
+- scale
 
 Installation Prerequisites
 --------------------------
@@ -43,6 +44,7 @@ can issue the command create, it takes two arguments the path where the
 docker-compose.yml will be stored and the content of this latter:
 
 .. code-block:: bash
+
     # salt-call -l debug dockercompose.create /tmp/toto '
      database:
      image: mongo:3.0
@@ -54,25 +56,25 @@ argument (the path where the docker-compose.yml will be read) and an optional
 python list which corresponds to the services names:
 
 .. code-block:: bash
+
     # salt-call -l debug dockercompose.up /tmp/toto
     # salt-call -l debug dockercompose.restart /tmp/toto '[database]'
     # salt-call -l debug dockercompose.stop /tmp/toto
     # salt-call -l debug dockercompose.rm /tmp/toto
 
-
 Docker-compose method supported
 -------------------------------
- - up
+- up
- - restart
+- restart
- - stop
+- stop
- - start
+- start
- - pause
+- pause
- - unpause
+- unpause
- - kill
+- kill
- - rm
+- rm
- - ps
+- ps
- - pull
+- pull
- - build
+- build
 
 Functions
 ---------