Merge pull request #55566 from terminalmage/clarify-outputter-docs

Clarify the outputter docs with CLI examples

salt/output/json_out.py

@@ -28,6 +28,13 @@
     {"mike": {"en0": {"hwaddr": "02:48:a2:4b:70:a0", ...}}}
     {"phill": {"en0": {"hwaddr": "02:1d:cc:a2:33:55", ...}}}
     {"stuart": {"en0": {"hwaddr": "02:9a:e0:ea:9e:3c", ...}}}
+
+
+CLI Example:
+
+.. code-block:: bash
+
+    salt '*' foo.bar --out=json
 '''
 from __future__ import absolute_import, print_function, unicode_literals
 

salt/output/newline_values_only.py

@@ -27,6 +27,10 @@
 Example 1
 ~~~~~~~~~
 
+.. code-block:: bash
+
+    salt '*' foo.bar --out=newline_values_only
+
 Input
 -----
 
@@ -40,7 +44,7 @@
 Output
 ------
 
-.. code-block:: python
+.. code-block:: text
 
     127.0.0.1
     10.0.0.1
@@ -50,6 +54,10 @@
 Example 2
 ~~~~~~~~~
 
+.. code-block:: bash
+
+    salt '*' foo.bar --out=newline_values_only
+
 Input
 -----
 

salt/output/no_out_quiet.py

@@ -4,6 +4,12 @@
 =================
 
 No output is produced when this outputter is selected
+
+CLI Example:
+
+.. code-block:: bash
+
+    salt '*' foo.bar --out=quiet
 '''
 
 # Define the module's virtual name

salt/output/pony.py

@@ -39,6 +39,12 @@
                █▄▄██████   █▄▄██████
                  █▄▄▄▄█       █▄▄▄▄█
 
+
+CLI Example:
+
+.. code-block:: bash
+
+    salt '*' foo.bar --out=pony
 '''
 
 # Import Python libs

salt/output/pprint_out.py

@@ -6,7 +6,15 @@
 The python pretty-print system was once the default outputter. It simply
 passes the return data through to ``pprint.pformat`` and prints the results.
 
-Example output::
+CLI Example:
+
+.. code-block:: bash
+
+    salt '*' foo.bar --out=pprint
+
+Example output:
+
+.. code-block:: python
 
     {'saltmine': {'foo': {'bar': 'baz',
                           'dictionary': {'abc': 123, 'def': 456},

salt/output/profile.py

@@ -5,7 +5,11 @@
 
 Show profile data for returners that would normally show a highstate output.
 
-    salt MINION state.apply something --out=profile
+CLI Example:
+
+.. code-block:: bash
+
+    salt '*' state.apply something --out=profile
 
 Attempt to output the returns of state.sls and state.highstate as a table of
 names, modules and durations that looks somewhat like the following::

salt/output/raw.py

@@ -11,8 +11,17 @@
 This was the original outputter used by Salt before the outputter system was
 developed.
 
-Example output::
+CLI Example:
 
+.. code-block:: bash
+
+    salt '*' foo.bar --out=raw
+
+Example output:
+
+.. code-block:: python
+
+    salt '*' foo.bar --out=table
     {'myminion': {'foo': {'list': ['Hello', 'World'], 'bar': 'baz', 'dictionary': {'abc': 123, 'def': 456}}}}
 '''
 

salt/output/table_out.py

@@ -5,9 +5,11 @@
 
 .. versionadded:: 2017.7.0
 
-This outputter displays a sequence of rows as table.
+The ``table`` outputter displays a sequence of rows as table.
 
-Example output::
+Example output:
+
+.. code-block:: text
 
     edge01.bjm01:
     ----------
@@ -32,6 +34,13 @@
             ______________________________________________________________________________
         result:
         ----------
+
+
+CLI Example:
+
+.. code-block:: bash
+
+    salt '*' foo.bar --out=table
 '''
 
 # Import Python libs

salt/output/txt.py

@@ -3,9 +3,14 @@
 Simple text outputter
 =====================
 
-The txt outputter has been developed to make the output from shell
-commands on minions appear as they do when the command is executed
-on the minion.
+The ``txt`` outputter has been developed to make the output from shell commands
+on minions appear as they do when the command is executed on the minion.
+
+CLI Example:
+
+.. code-block:: bash
+
+    salt '*' foo.bar --out=txt
 '''
 from __future__ import absolute_import, print_function, unicode_literals
 

salt/output/yaml_out.py

@@ -5,7 +5,17 @@
 
 This outputter defaults to printing in YAML block mode for better readability.
 
-Example output::
+CLI Example:
+
+.. code-block:: bash
+
+    salt '*' foo.bar --out=yaml
+
+Example output:
+
+CLI Example:
+
+.. code-block:: python
 
     saltmine:
       foo: