Add CLI examples for runners

These make the docs look better.

salt/runners/cache.py

@@ -16,14 +16,21 @@ log = logging.getLogger(__name__)
 deprecation_warning = ("The 'minion' arg will be removed from "
                     "cache.py runner. Specify minion with 'tgt' arg!")
 
+
 def grains(tgt=None, expr_form='glob', **kwargs):
     '''
     Return cached grains of the targeted minions
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt-run cache.grains
     '''
     deprecated_minion = kwargs.get('minion', None)
     if tgt is None and deprecated_minion is None:
         log.warn("DEPRECATION WARNING: {0}".format(deprecation_warning))
-        tgt = '*' # targat all minions for backward compatibility
+        tgt = '*'  # targat all minions for backward compatibility
     elif tgt is None and isinstance(deprecated_minion, string_types):
         log.warn("DEPRECATION WARNING: {0}".format(deprecation_warning))
         tgt = deprecated_minion
@@ -41,11 +48,17 @@ def grains(tgt=None, expr_form='glob', **kwargs):
 def pillar(tgt=None, expr_form='glob', **kwargs):
     '''
     Return cached pillars of the targeted minions
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt-run cache.pillar
     '''
     deprecated_minion = kwargs.get('minion', None)
     if tgt is None and deprecated_minion is None:
         log.warn("DEPRECATION WARNING: {0}".format(deprecation_warning))
-        tgt = '*' # targat all minions for backward compatibility
+        tgt = '*'  # targat all minions for backward compatibility
     elif tgt is None and isinstance(deprecated_minion, string_types):
         log.warn("DEPRECATION WARNING: {0}".format(deprecation_warning))
         tgt = deprecated_minion

salt/runners/doc.py

@@ -19,6 +19,12 @@ def __virtual__():
 def runner():
     '''
     Return all inline documetation for runner modules
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt-run doc.runner
     '''
     client = salt.runner.RunnerClient(__opts__)
     ret = client.get_docs()
@@ -29,6 +35,12 @@ def runner():
 def wheel():
     '''
     Return all inline documentation for wheel modules
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt-run doc.wheel
     '''
     client = salt.wheel.Wheel(__opts__)
     ret = client.get_docs()
@@ -39,6 +51,12 @@ def wheel():
 def execution():
     '''
     Collect all the sys.doc output from each minion and return the aggregate
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt-run doc.execution
     '''
     client = salt.client.LocalClient(__opts__['conf_file'])
 

salt/runners/fileserver.py

@@ -9,6 +9,12 @@ import salt.fileserver
 def update():
     '''
     Execute an update for all of the configured fileserver backends
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt-run fileserver.update
     '''
     fileserver = salt.fileserver.Fileserver(__opts__)
     fileserver.update()

salt/runners/jobs.py

@@ -17,6 +17,12 @@ def active():
     '''
     Return a report on all actively running jobs from a job id centric
     perspective
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt-run jobs.active
     '''
     ret = {}
     client = salt.client.LocalClient(__opts__['conf_file'])
@@ -54,6 +60,12 @@ def active():
 def lookup_jid(jid, ext_source=None):
     '''
     Return the printout from a previously executed job
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt-run jobs.lookup_jid 20130916125524463507
     '''
     ret = {}
     if __opts__['ext_job_cache'] or ext_source:
@@ -87,6 +99,12 @@ def lookup_jid(jid, ext_source=None):
 def list_jobs():
     '''
     List all detectable jobs and associated functions
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt-run jobs.list_jobs
     '''
     serial = salt.payload.Serial(__opts__)
     ret = {}
@@ -112,6 +130,12 @@ def list_jobs():
 def print_job(job_id):
     '''
     Print job available details, including return data.
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt-run jobs.print_job
     '''
     serial = salt.payload.Serial(__opts__)
     ret = {}

salt/runners/launchd.py

@@ -6,6 +6,12 @@ import sys
 def write_launchd_plist(program):
     '''
     Write a launchd plist for managing salt-master or salt-minion
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt-run launchd.write_launchd_plist salt-master
     '''
     plist_sample_text = """
 <?xml version="1.0" encoding="UTF-8"?>

salt/runners/manage.py

@@ -15,6 +15,12 @@ import salt.output
 def status(output=True):
     '''
     Print the status of all known salt minions
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt-run manage.status
     '''
     client = salt.client.LocalClient(__opts__['conf_file'])
     minions = client.cmd('*', 'test.ping', timeout=__opts__['timeout'])
@@ -48,6 +54,12 @@ def key_regen():
 
     Only Execute this runner after upgrading minions and master to 0.15.1 or
     higher!
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt-run manage.key_regen
     '''
     client = salt.client.LocalClient(__opts__['conf_file'])
     minions = client.cmd('*', 'saltutil.regen_keys')
@@ -75,6 +87,12 @@ def key_regen():
 def down():
     '''
     Print a list of all the down or unresponsive salt minions
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt-run manage.down
     '''
     ret = status(output=False).get('down', [])
     for minion in ret:
@@ -85,6 +103,12 @@ def down():
 def up():  # pylint: disable=C0103
     '''
     Print a list of all of the minions that are up
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt-run manage.up
     '''
     ret = status(output=False).get('up', [])
     for minion in ret:
@@ -95,6 +119,12 @@ def up():  # pylint: disable=C0103
 def versions():
     '''
     Check the version of active minions
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt-run manage.versions
     '''
     client = salt.client.LocalClient(__opts__['conf_file'])
     minions = client.cmd('*', 'test.version', timeout=__opts__['timeout'])

salt/runners/network.py

@@ -14,7 +14,9 @@ def wollist(maclist, bcast='255.255.255.255', destport=9):
     Send a "Magic Packet" to wake up a list of Minions.
     This list must contain one MAC hardware address per line
 
-    CLI Example::
+    CLI Example:
+
+    .. code-block:: bash
 
         salt-run network.wollist '/path/to/maclist'
         salt-run network.wollist '/path/to/maclist' 255.255.255.255 7
@@ -37,7 +39,9 @@ def wol(mac, bcast='255.255.255.255', destport=9):
     '''
     Send a "Magic Packet" to wake up a Minion
 
-    CLI Example::
+    CLI Example:
+
+    .. code-block:: bash
 
         salt-run network.wol 08-00-27-13-69-77
         salt-run network.wol 080027136977 255.255.255.255 7

salt/runners/search.py

@@ -10,6 +10,12 @@ import salt.output
 def query(term):
     '''
     Query the search system
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt-run search.query foo
     '''
     search = salt.search.Search(__opts__)
     result = search.query(term)

salt/runners/state.py

@@ -11,6 +11,13 @@ def over(env='base', os_fn=None):
     '''
     Execute an overstate sequence to orchestrate the executing of states
     over a group of systems
+
+    CLI Examples:
+
+    .. code-block:: bash
+
+        salt-run state.over
+        salt-run state.over env=dev /root/overstate.sls
     '''
     stage_num = 0
     overstate = salt.overstate.OverState(__opts__, env, os_fn)
@@ -44,6 +51,13 @@ def sls(mods, env='base', test=None, exclude=None):
     '''
     Execute a state run from the master, used as a powerful orchestration
     system.
+
+    CLI Examples:
+
+    .. code-block:: bash
+
+        salt-run state.sls webserver
+        salt-run state.sls webserver env=dev test=True
     '''
     __opts__['file_client'] = 'local'
     minion = salt.minion.MasterMinion(__opts__)
@@ -56,6 +70,13 @@ def sls(mods, env='base', test=None, exclude=None):
 def show_stages(env='base', os_fn=None):
     '''
     Display the stage data to be executed
+
+    CLI Examples:
+
+    .. code-block:: bash
+
+        salt-run state.show_stages
+        salt-run state.show_stages env=dev /root/overstate.sls
     '''
     overstate = salt.overstate.OverState(__opts__, env, os_fn)
     salt.output.display_output(

salt/runners/winrepo.py

@@ -22,6 +22,12 @@ log = logging.getLogger(__name__)
 def genrepo():
     '''
     Generate win_repo_cachefile based on sls files in the win_repo
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt-run winrepo.genrepo
     '''
     ret = {}
     repo = __opts__['win_repo']
@@ -60,6 +66,12 @@ def genrepo():
 def update_git_repos():
     '''
     Checkout git repos containing Windows Software Package Definitions
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt-run winrepo.update_git_repos
     '''
     ret = {}
     mminion = salt.minion.MasterMinion(__opts__)