From 320f6be10a4ea8e7f7447634d577fd3ab9f6bd27 Mon Sep 17 00:00:00 2001 From: Erik Johnson Date: Mon, 16 Sep 2013 13:55:15 -0500 Subject: [PATCH] Add CLI examples for runners These make the docs look better. --- salt/runners/cache.py | 17 +++++++++++++++-- salt/runners/doc.py | 18 ++++++++++++++++++ salt/runners/fileserver.py | 6 ++++++ salt/runners/jobs.py | 24 ++++++++++++++++++++++++ salt/runners/launchd.py | 6 ++++++ salt/runners/manage.py | 30 ++++++++++++++++++++++++++++++ salt/runners/network.py | 8 ++++++-- salt/runners/search.py | 6 ++++++ salt/runners/state.py | 21 +++++++++++++++++++++ salt/runners/winrepo.py | 12 ++++++++++++ 10 files changed, 144 insertions(+), 4 deletions(-) diff --git a/salt/runners/cache.py b/salt/runners/cache.py index 88289c78ec..bb24199763 100644 --- a/salt/runners/cache.py +++ b/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 diff --git a/salt/runners/doc.py b/salt/runners/doc.py index 22dda1e3da..c586a9e892 100644 --- a/salt/runners/doc.py +++ b/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']) diff --git a/salt/runners/fileserver.py b/salt/runners/fileserver.py index 7c268958c7..23e738b1a1 100644 --- a/salt/runners/fileserver.py +++ b/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() diff --git a/salt/runners/jobs.py b/salt/runners/jobs.py index 9abf7c3318..836a077fb4 100644 --- a/salt/runners/jobs.py +++ b/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 = {} diff --git a/salt/runners/launchd.py b/salt/runners/launchd.py index f1701fd9c6..4aaa32973f 100644 --- a/salt/runners/launchd.py +++ b/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 = """ diff --git a/salt/runners/manage.py b/salt/runners/manage.py index acd4a95240..5e60273344 100644 --- a/salt/runners/manage.py +++ b/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']) diff --git a/salt/runners/network.py b/salt/runners/network.py index 7e523b9656..932bede059 100644 --- a/salt/runners/network.py +++ b/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 diff --git a/salt/runners/search.py b/salt/runners/search.py index 8a18f2c4b5..0981d198db 100644 --- a/salt/runners/search.py +++ b/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) diff --git a/salt/runners/state.py b/salt/runners/state.py index 1160c645f1..2315461747 100644 --- a/salt/runners/state.py +++ b/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( diff --git a/salt/runners/winrepo.py b/salt/runners/winrepo.py index 024eda16c2..0006b758a6 100644 --- a/salt/runners/winrepo.py +++ b/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__)