Start checking rst files at pre-commit level with rstcheck

Additionally, fixed most of the errors reported by rstcheck.

Fixes https://github.com/saltstack/salt/issues/58668

.pre-commit-config.yaml

@@ -1112,6 +1112,16 @@ repos:
                 tests/kitchen/.*
             )$
 
+  - repo: https://github.com/myint/rstcheck
+    # This, for now, is meant to run when locally committing code and will be disabled(skipped) when we run pre-commit
+    # against all codebase to avoid MASSIVE code churn. This way, we do it in smaller chunks, a few at a time.
+    rev: 3f92957
+    hooks:
+      - id: rstcheck
+        name: Check reST files using rstcheck
+        args: [--report=warning]
+        additional_dependencies: [sphinx]
+
   - repo: https://github.com/asottile/blacken-docs
     rev: v1.7.0
     hooks:

.rstcheck.cfg

@@ -0,0 +1,27 @@
+[rstcheck]
+ignore_directives=
+  automodule,
+  autoclass,
+  autofunction,
+  conf_proxy,
+  conf_log,
+  conf_master,
+  conf_minion,
+  releasestree,
+  jinja_ref,
+  salt:event
+ignore_roles=
+  conf_master,
+  conf_minion,
+  conf_proxy,
+  conf_log,
+  formula_url,
+  issue,
+  pull,
+  blob,
+  jinja_ref
+ignore_substitutions=
+  saltrepo,
+  repo_primary_branch,
+  windownload,
+  osxdownloadpy3

cicd/jenkins/pre-commit

@@ -5,7 +5,7 @@ if (env.CHANGE_ID) {
     pre_commit_skips = ''
 } else {
     // This is a branch build
-    pre_commit_skips = 'pyupgrade,remove-import-headers'
+    pre_commit_skips = 'pyupgrade,remove-import-headers,rstcheck'
 }
 
 runPreCommit(

doc/ref/configuration/master.rst

@@ -14,8 +14,8 @@ of the Salt system each have a respective configuration file. The
     :ref:`Example master configuration file <configuration-examples-master>`.
 
 The configuration file for the salt-master is located at ``/etc/salt/master``
-by default. Atomic included configuration files can be placed in 
-``/etc/salt/master.d/*.conf``. Warning: files with other suffixes than .conf will 
+by default. Atomic included configuration files can be placed in
+``/etc/salt/master.d/*.conf``. Warning: files with other suffixes than .conf will
 not be included. A notable exception is FreeBSD, where the configuration file is
 located at ``/usr/local/etc/salt``. The available options are as follows:
 
@@ -2022,7 +2022,7 @@ Each minion connecting to the master uses AT LEAST one file descriptor, the
 master subscription connection. If enough minions connect you might start
 seeing on the console(and then salt-master crashes):
 
-.. code-block:: bash
+.. code-block:: text
 
     Too many open files (tcp_listener.cpp:335)
     Aborted (core dumped)

doc/ref/modules/index.rst

@@ -97,7 +97,7 @@ included libraries.
 
 Then, create the zip:
 
-.. code-block:: bash
+.. code-block:: console
 
     modules $ zip -r lumberjack lumberjack
       adding: lumberjack/ (stored 0%)

doc/ref/runners/index.rst

@@ -125,4 +125,4 @@ responding to Salt calls could look like this:
         client = salt.client.LocalClient(__opts__["conf_file"])
         minions = client.cmd("*", "test.version", timeout=1)
         for minion in sorted(minions):
-            print minion
+            print(minion)

doc/ref/states/requisites.rst

@@ -363,6 +363,8 @@ shown in json for clarity:
         }
     }
 
+.. code-block:: json
+
     {
         "local": {
             "pkgrepo_|-salt-minion_|-salt-minion_|-managed": {

doc/ref/states/writing.rst

@@ -66,11 +66,12 @@ A well-written state function will follow these steps:
 
    .. code-block:: python
 
-       ret = {"name": name, "result": False, "changes": {}, "comment": ""}
+       def myfunc():
+           ret = {"name": name, "result": False, "changes": {}, "comment": ""}
 
-       if foo and bar:
-           ret["comment"] = "Only one of foo and bar is permitted"
-           return ret
+           if foo and bar:
+               ret["comment"] = "Only one of foo and bar is permitted"
+               return ret
 
 2. Check if changes need to be made. This is best done with an
    information-gathering function in an accompanying :ref:`execution module
@@ -87,10 +88,11 @@ A well-written state function will follow these steps:
 
    .. code-block:: python
 
-       if result:
-           ret["result"] = True
-           ret["comment"] = "{0} is already installed".format(name)
-           return ret
+       def myfunc():
+           if result:
+               ret["result"] = True
+               ret["comment"] = "{0} is already installed".format(name)
+               return ret
 
 4. If step 2 found that changes *do* need to be made, then check to see if the
    state was being run in test mode (i.e. with ``test=True``). If so, then exit
@@ -99,11 +101,12 @@ A well-written state function will follow these steps:
 
    .. code-block:: python
 
-       if __opts__["test"]:
-           ret["result"] = None
-           ret["comment"] = "{0} would be installed".format(name)
-           ret["changes"] = result
-           return ret
+       def myfunc():
+           if __opts__["test"]:
+               ret["result"] = None
+               ret["comment"] = "{0} would be installed".format(name)
+               ret["changes"] = result
+               return ret
 
 5. Make the desired changes. This should again be done using a function from an
    accompanying execution module. If the result of that function is enough to
@@ -132,13 +135,14 @@ A well-written state function will follow these steps:
 
    .. code-block:: python
 
-       if ret["changes"]:
-           ret["comment"] = "{0} failed to install".format(name)
-       else:
-           ret["result"] = True
-           ret["comment"] = "{0} was installed".format(name)
+       def myfunc():
+           if ret["changes"]:
+               ret["comment"] = "{0} failed to install".format(name)
+           else:
+               ret["result"] = True
+               ret["comment"] = "{0} was installed".format(name)
 
-       return ret
+           return ret
 
 Using Custom State Modules
 ==========================
@@ -307,11 +311,12 @@ run. An example of such a check could look like this:
 
 .. code-block:: python
 
-    # Return comment of changes if test.
-    if __opts__["test"]:
-        ret["result"] = None
-        ret["comment"] = "State Foo will execute with param {0}".format(bar)
-        return ret
+    def myfunc():
+        # Return comment of changes if test.
+        if __opts__["test"]:
+            ret["result"] = None
+            ret["comment"] = "State Foo will execute with param {0}".format(bar)
+            return ret
 
 Make sure to test and return before performing any real actions on the minion.
 

doc/topics/cloud/aws.rst

@@ -949,7 +949,7 @@ Alternate Endpoint
 Normally, EC2 endpoints are build using the region and the service_url. The
 resulting endpoint would follow this pattern:
 
-.. code-block:: bash
+.. code-block:: text
 
     ec2.<region>.<service_url>
 

doc/topics/cloud/cloudstack.rst

@@ -119,7 +119,7 @@ command:
 Images can be obtained using the ``--list-images`` option for the ``salt-cloud``
 command:
 
-.. code-block:: bash
+.. code-block:: console
 
     # salt-cloud --list-images exoscale
     exoscale:

doc/topics/cloud/config.rst

@@ -652,36 +652,38 @@ data:
 
 .. code-block:: python
 
-    "providers": {
-        "my-develop-envs": [
-            {
-                "availability_zone": "ap-southeast-1b",
-                "id": "HJGRYCILJLKJYG",
-                "key": "kdjgfsgm;woormgl/aserigjksjdhasdfgn",
-                "keyname": "test",
-                "location": "ap-southeast-1",
-                "private_key": "/root/test.pem",
-                "driver": "aws",
-                "securitygroup": "quick-start",
-            },
-            {
-                "location": "Raleigh",
-                "password": "mypass",
-                "driver": "ibmsce",
-                "ssh_key_file": "/etc/salt/ibm/mykey.pem",
-                "ssh_key_name": "mykey",
-                "user": "myuser@mycorp.com",
-            },
-        ],
-        "my-productions-envs": [
-            {
-                "availability_zone": "us-east-1",
-                "location": "us-east-1",
-                "password": "mypass",
-                "driver": "ibmsce",
-                "ssh_key_file": "/etc/salt/ibm/mykey.pem",
-                "ssh_key_name": "mykey",
-                "user": "my-production-user@mycorp.com",
-            }
-        ],
+    {
+        "providers": {
+            "my-develop-envs": [
+                {
+                    "availability_zone": "ap-southeast-1b",
+                    "id": "HJGRYCILJLKJYG",
+                    "key": "kdjgfsgm;woormgl/aserigjksjdhasdfgn",
+                    "keyname": "test",
+                    "location": "ap-southeast-1",
+                    "private_key": "/root/test.pem",
+                    "driver": "aws",
+                    "securitygroup": "quick-start",
+                },
+                {
+                    "location": "Raleigh",
+                    "password": "mypass",
+                    "driver": "ibmsce",
+                    "ssh_key_file": "/etc/salt/ibm/mykey.pem",
+                    "ssh_key_name": "mykey",
+                    "user": "myuser@mycorp.com",
+                },
+            ],
+            "my-productions-envs": [
+                {
+                    "availability_zone": "us-east-1",
+                    "location": "us-east-1",
+                    "password": "mypass",
+                    "driver": "ibmsce",
+                    "ssh_key_file": "/etc/salt/ibm/mykey.pem",
+                    "ssh_key_name": "mykey",
+                    "user": "my-production-user@mycorp.com",
+                }
+            ],
+        }
     }

doc/topics/cloud/dimensiondata.rst

@@ -74,7 +74,7 @@ command --list-sizes is run a default will be returned).
 Images can be obtained using the ``--list-images`` option for the ``salt-cloud``
 command:
 
-.. code-block:: bash
+.. code-block:: console
 
     # salt-cloud --list-images my-dimensiondata-config
     my-dimensiondata-config:

doc/topics/cloud/gogrid.rst

@@ -89,7 +89,7 @@ command:
 Images can be obtained using the ``--list-images`` option for the ``salt-cloud``
 command:
 
-.. code-block:: bash
+.. code-block:: console
 
     # salt-cloud --list-images my-gogrid-config
     my-gogrid-config:

doc/topics/cloud/joyent.rst

@@ -93,7 +93,7 @@ command:
 Images can be obtained using the ``--list-images`` option for the ``salt-cloud``
 command:
 
-.. code-block:: bash
+.. code-block:: console
 
     # salt-cloud --list-images my-joyent-config
     my-joyent-config:

doc/topics/cloud/qs.rst

@@ -67,7 +67,7 @@ List Cloud Provider Options
 You can now query the cloud provider you configured for available locations,
 images, and sizes. This information is used when you set up VM profiles.
 
-.. code-block:: bash
+.. code-block:: console
 
     salt-cloud --list-locations <provider_name>  # my-ec2 in the previous example
     salt-cloud --list-images <provider_name>
@@ -109,7 +109,7 @@ Create VMs
 ----------
 VMs are created by calling ``salt-cloud`` with the following options:
 
-.. code-block:: bash
+.. code-block:: console
 
     salt-cloud -p <profile> <name1> <name2> ...
 

doc/topics/cloud/scaleway.rst

@@ -47,7 +47,7 @@ Set up an initial profile at /etc/salt/cloud.profiles or in the /etc/salt/cloud.
 
 Images can be obtained using the ``--list-images`` option for the ``salt-cloud`` command:
 
-.. code-block:: bash
+.. code-block:: console
 
     #salt-cloud --list-images my-scaleway-config
     my-scaleway-config:
@@ -81,7 +81,7 @@ Images can be obtained using the ``--list-images`` option for the ``salt-cloud``
 
 Execute a query and return all information about the nodes running on configured cloud providers using the ``-Q`` option for the ``salt-cloud`` command:
 
-.. code-block:: bash
+.. code-block:: console
 
     # salt-cloud -F
     [INFO    ] salt-cloud starting

doc/topics/cloud/troubleshooting.rst

@@ -122,7 +122,7 @@ following command:
 The if the output of this command includes a line that looks like this, then
 the ``/tmp/`` directory is mounted as ``noexec``:
 
-.. code-block:: bash
+.. code-block:: console
 
     tmpfs on /tmp type tmpfs (rw,noexec)
 

doc/topics/cloud/vagrant.rst

@@ -243,7 +243,7 @@ Create and use your new Salt minion
 
 .. _this gist: https://github.com/jirsbek/SSH-keys-in-macOS-Sierra-keychain
 
-.. code-block:: bash
+.. code-block:: console
 
     ssh -A vagrant@< the bridged network address >
       # [ or, if you are at /home/my_username/ on my_laptop ]
@@ -251,7 +251,7 @@ Create and use your new Salt minion
 
 - then typing on your new node "v1" (a.k.a. quail1.bevy1.test)...
 
-.. code-block:: bash
+.. code-block:: console
 
     password: vagrant
       # [ stuff types out ... ]

doc/topics/development/hacking.rst

@@ -172,7 +172,7 @@ If you would like to log to the console instead of to the log file, remove the
 
     Once the minion starts, you may see an error like the following:
 
-    .. code-block:: bash
+    .. code-block:: console
 
         zmq.core.error.ZMQError: ipc path "/path/to/your/virtualenv/
         var/run/salt/minion/minion_event_7824dcbcfd7a8f6755939af70b96249f_pub.ipc"

doc/topics/development/package_providers.rst

@@ -82,6 +82,7 @@ Deprecated and destined to be removed. For now, should just do the following:
 
 .. code-block:: python
 
+    def myfunc():
         return __salt__["pkg.latest_version"](name) != ""
 
 
@@ -138,7 +139,8 @@ return the output of ``salt.utils.data.compare_dicts()``:
 
 .. code-block:: python
 
-    return salt.utils.data.compare_dicts(old, new)
+    def myfunc():
+        return salt.utils.data.compare_dicts(old, new)
 
 
 remove
@@ -174,7 +176,7 @@ Lists the repositories that are currently configured on this system.
 
 Returns a dictionary, in the following format:
 
-.. code-block:: python
+.. code-block:: pycon
 
     {'reponame': 'config_key_1': 'config value 1',
                  'config_key_2': 'config value 2',
@@ -192,7 +194,7 @@ Displays all local configuration for a specific repository.
 The information is formatted in much the same way as list_repos, but is
 specific to only one repo.
 
-.. code-block:: python
+.. code-block:: pycon
 
     {'config_key_1': 'config value 1',
      'config_key_2': 'config value 2',

doc/topics/development/tests/integration.rst

@@ -347,18 +347,19 @@ Testing salt-ssh functionality can be done using the SSHCase test class:
 
     from tests.support.case import SSHCase
 
-    class SSHGrainsTest(SSHCase):
-    '''
-    Test salt-ssh grains functionality
-    Depend on proper environment set by integration.SSHCase class
-    '''
 
-    def test_grains_id(self):
-        '''
-        Test salt-ssh grains id work for localhost.
-        '''
-        cmd = self.run_function('grains.get', ['id'])
-        self.assertEqual(cmd, 'localhost')
+    class SSHGrainsTest(SSHCase):
+        """
+        Test salt-ssh grains functionality
+        Depend on proper environment set by integration.SSHCase class
+        """
+
+        def test_grains_id(self):
+            """
+            Test salt-ssh grains id work for localhost.
+            """
+            cmd = self.run_function("grains.get", ["id"])
+            self.assertEqual(cmd, "localhost")
 
 
 Testing Event System via SaltMinionEventAssertsMixin
@@ -582,43 +583,42 @@ contain valid information are also required in the test class's ``setUp`` functi
     from tests.support.case import ShellCase
     from tests.support.paths import FILES
 
+
     class LinodeTest(ShellCase):
-    '''
-    Integration tests for the Linode cloud provider in Salt-Cloud
-    '''
+        """
+        Integration tests for the Linode cloud provider in Salt-Cloud
+        """
 
-    def setUp(self):
-        '''
-        Sets up the test requirements
-        '''
-        super(LinodeTest, self).setUp()
+        def setUp(self):
+            """
+            Sets up the test requirements
+            """
+            super(LinodeTest, self).setUp()
 
-        # check if appropriate cloud provider and profile files are present
-        profile_str = 'linode-config:'
-        provider = 'linode'
-        providers = self.run_cloud('--list-providers')
-        if profile_str not in providers:
-            self.skipTest(
-                'Configuration file for {0} was not found. Check {0}.conf files '
-                'in tests/integration/files/conf/cloud.*.d/ to run these tests.'
-                .format(provider)
-            )
-
-        # check if apikey and password are present
-        path = os.path.join(FILES,
-                            'conf',
-                            'cloud.providers.d',
-                            provider + '.conf')
-        config = cloud_providers_config(path)
-        api = config['linode-config']['linode']['apikey']
-        password = config['linode-config']['linode']['password']
-        if api == '' or password == '':
-            self.skipTest(
-                'An api key and password must be provided to run these tests. Check '
-                'tests/integration/files/conf/cloud.providers.d/{0}.conf'.format(
-                    provider
+            # check if appropriate cloud provider and profile files are present
+            profile_str = "linode-config:"
+            provider = "linode"
+            providers = self.run_cloud("--list-providers")
+            if profile_str not in providers:
+                self.skipTest(
+                    "Configuration file for {0} was not found. Check {0}.conf files "
+                    "in tests/integration/files/conf/cloud.*.d/ to run these tests.".format(
+                        provider
+                    )
+                )
+
+            # check if apikey and password are present
+            path = os.path.join(FILES, "conf", "cloud.providers.d", provider + ".conf")
+            config = cloud_providers_config(path)
+            api = config["linode-config"]["linode"]["apikey"]
+            password = config["linode-config"]["linode"]["password"]
+            if api == "" or password == "":
+                self.skipTest(
+                    "An api key and password must be provided to run these tests. Check "
+                    "tests/integration/files/conf/cloud.providers.d/{0}.conf".format(
+                        provider
+                    )
                 )
-            )
 
 Repeatedly creating and destroying instances on cloud providers can be costly.
 Therefore, cloud provider tests are off by default and do not run automatically. To

doc/topics/development/tutorial.rst

@@ -146,7 +146,7 @@ Push
 Push your branch to your GitHub account.  You will likely need to enter your
 GitHub username and password.
 
-.. code-block:: bash
+.. code-block:: console
 
     $ git push origin virt_ret
     Username for 'https://github.com': <my_account>
@@ -159,7 +159,7 @@ GitHub username and password.
     you have done this, you may need add the keys to your git repository
     configuration
 
-    .. code-block:: bash
+    .. code-block:: console
 
         $ git config ssh.key ~/.ssh/<key_name>
 

doc/topics/event/events.rst

@@ -247,10 +247,9 @@ done at the CLI:
 
     caller = salt.client.Caller()
 
-    ret = caller.cmd('event.send',
-                     'myco/event/success'
-                     { 'success': True,
-                       'message': "It works!" })
+    ret = caller.cmd(
+        "event.send", "myco/event/success", {"success": True, "message": "It works!"}
+    )
 
     if not ret:
         # the event could not be sent, process the error here

doc/topics/grains/index.rst

@@ -217,7 +217,7 @@ grain data structure. For example, consider this custom grain file:
 
 The output of this example renders like so:
 
-.. code-block:: bash
+.. code-block:: console
 
     # salt-call --local grains.items
     local:
@@ -235,7 +235,7 @@ the function will be rendered twice by Salt in the items output: once for the
 ``my_custom_grain`` call itself, and again when it is called in the ``main``
 function:
 
-.. code-block:: bash
+.. code-block:: console
 
     # salt-call --local grains.items
     local:

doc/topics/installation/eos.rst

@@ -6,7 +6,7 @@ The Salt minion for Arista EOS is distributed as a SWIX extension and can be ins
 
 .. note::
 
-    This SWIX extension has been tested on Arista DCS-7280SE-68-R, running EOS 4.17.5M and vEOS 4.18.3F. 
+    This SWIX extension has been tested on Arista DCS-7280SE-68-R, running EOS 4.17.5M and vEOS 4.18.3F.
 
 Important Notes
 ===============
@@ -46,8 +46,8 @@ Verify the installation
 
 .. code-block:: bash
 
-    veos#show extensions | include salt-eos      
-         salt-eos-2017-07-19.swix      1.0.11/1.fc25        A, F                27   
+    veos#show extensions | include salt-eos
+         salt-eos-2017-07-19.swix      1.0.11/1.fc25        A, F                27
 
 Change the Salt master IP address or FQDN, by edit the variable (SALT_MASTER)
 
@@ -55,9 +55,9 @@ Change the Salt master IP address or FQDN, by edit the variable (SALT_MASTER)
 
     veos#bash vi /mnt/flash/startup.sh
 
-Make sure you enable the eAPI with unix-socket 
+Make sure you enable the eAPI with unix-socket
 
-.. code-block:: bash
+.. code-block:: console
 
     veos(config)#management api http-commands
              protocol unix-socket
@@ -70,7 +70,7 @@ Generate Keys and host record and start Salt minion
 
 .. code-block:: bash
 
-   veos#bash 
+   veos#bash
    #sudo /mnt/flash/startup.sh
 
 ``salt-minion`` should be running
@@ -79,14 +79,14 @@ Copy the installed extensions to boot-extensions
 
 .. code-block:: bash
 
-   veos#copy installed-extensions boot-extensions 
+   veos#copy installed-extensions boot-extensions
 
-Apply event-handler to let EOS start salt-minion during boot-up 
+Apply event-handler to let EOS start salt-minion during boot-up
 
-.. code-block:: bash
+.. code-block:: console
 
-   veos(config)#event-handler boot-up-script       
-      trigger on-boot                 
+   veos(config)#event-handler boot-up-script
+      trigger on-boot
       action bash sudo /mnt/flash/startup.sh
 
 For more specific installation details of the ``salt-minion``, please refer to :ref:`Configuring Salt<configuring-salt>`.
@@ -112,7 +112,7 @@ If you decide to uninstall this package, the following steps are recommended for
 
 2. Remove boot-up script
 
-.. code-block:: bash
+.. code-block:: console
 
    veos(config)#no event-handler boot-up-script
 

doc/topics/installation/nxos.rst

@@ -165,7 +165,7 @@ Starting in release ``9.2(1)`` and onward, the .ova file can be copied to the ``
 
 Copy the ``guestshell.ova`` file to ``volatile:`` if supported, otherwise copy it to ``bootflash:``
 
-.. code:: bash
+.. code-block:: console
 
   n3xxx# copy scp://admin@1.2.3.4/guestshell.ova volatile: vrf management
   guestshell.ova 100% 55MB 10.9MB/s 00:05
@@ -174,7 +174,7 @@ Copy the ``guestshell.ova`` file to ``volatile:`` if supported, otherwise copy i
 
 Use the ``guestshell enable`` command to install and enable guestshell.
 
-.. code:: bash
+.. code-block:: console
 
   n3xxx# guestshell enable package volatile:guestshell.ova
 
@@ -213,7 +213,7 @@ The ``guestshell`` container environment is enabled by default on most platforms
 
 **Example.** Allocate resources for guestshell by setting new limits to 500MB disk and 350MB memory.
 
-.. code:: bash
+.. code:: console
 
   n3k# guestshell resize rootfs 500
   n3k# guestshell resize memory 350
@@ -238,7 +238,7 @@ The ``guestshell`` is an independent CentOS container that does not inherit sett
 
 **OPTIONAL: Add DNS Configuration**
 
-.. code:: bash
+.. code:: console
 
   [root@guestshell guestshell]#  cat >> /etc/resolv.conf << EOF
   nameserver 10.0.0.202
@@ -248,7 +248,7 @@ The ``guestshell`` is an independent CentOS container that does not inherit sett
 
 **OPTIONAL: Define proxy server variables if needed to allow network access to SaltStack package repositories**
 
-.. code:: bash
+.. code:: console
 
   export http_proxy=http://proxy.yourdomain.com:<port>
   export https_proxy=https://proxy.yourdomain.com:<port>

doc/topics/jinja/index.rst

@@ -1348,7 +1348,7 @@ Example:
 
 Returns:
 
-.. code-block:: python
+.. code-block:: pycon
 
   {
     'body': '{
@@ -2205,7 +2205,7 @@ log at the ``profile`` level along with the render time of the block.
 The ``profile`` block in the ``example.sls`` state will emit the following log
 statement:
 
-.. code-block:: bash
+.. code-block:: console
 
     # salt-call --local -l profile state.apply example
     [...]
@@ -2241,7 +2241,7 @@ Using the same logic as the ``profile`` block, the ``import_yaml``,
 
 For ``import_*`` blocks, the ``profile`` log statement has the following form:
 
-.. code-block:: bash
+.. code-block:: console
 
     # salt-call --local -l profile state.apply example
     [...]

doc/topics/releases/2016.11.0.rst

@@ -240,7 +240,7 @@ Grains Changes
 
   New behavior:
 
-  .. code-block:: bash
+  .. code-block:: console
 
       root@master:~# salt 'testwin200' grains.item cpu_model
       testwin200:

doc/topics/releases/2019.2.0.rst

@@ -713,7 +713,7 @@ Alternatively, the newly-added :py:func:`pkg.show <salt.modules.aptpkg.show>`
 function can be used to get more detailed information about a given package and
 help determine what package name is correct:
 
-.. code-block:: bash
+.. code-block:: console
 
     # salt myminion pkg.show 'nginx*' filter=description,provides
     myminion:
@@ -955,7 +955,7 @@ Those who are using the :ref:`LocalClient <local-client>` (either directly,
 or implicitly via a :ref:`netapi module <all-netapi-modules>`) need to update
 their code to use ``tgt_type``.
 
-.. code-block:: python
+.. code-block:: pycon
 
     >>> import salt.client
     >>> local = salt.client.LocalClient()

doc/topics/releases/3000.rst

@@ -292,7 +292,7 @@ A new :py:func:`state <salt.states.keystore>` and
 Keystore files is now included. It allows for adding/removing/listing
 as well as managing keystore files.
 
-.. code-block:: bash
+.. code-block:: console
 
   # salt-call keystore.list /path/to/keystore.jks changeit
   local:

doc/topics/releases/releasecandidate.rst

@@ -115,7 +115,7 @@ Then install salt using the following command:
 
 .. code-block:: bash
 
-    sudo pip install salt==<rc tag version>
+    sudo pip install salt==$rc_tag_version
 
 For example for the 3002rc1 release:
 

doc/topics/spm/dev.rst

@@ -41,9 +41,10 @@ connection object, then that connection object is returned. For instance, the
 
 .. code-block:: python
 
-    conn = sqlite3.connect(__opts__["spm_db"], isolation_level=None)
-    ...
-    return conn
+   def myfunc():
+       conn = sqlite3.connect(__opts__["spm_db"], isolation_level=None)
+       ...
+       return conn
 
 SPM itself will not use this connection object; it will be passed in as-is to
 the other functions in the module. Therefore, when you set up this object, make

doc/topics/troubleshooting/index.rst

@@ -112,7 +112,7 @@ The salt-master needs at least 2 sockets per host that connects to it, one for
 the Publisher and one for response port. Thus, large installations may, upon
 scaling up the number of minions accessing a given master, encounter:
 
-.. code-block:: bash
+.. code-block:: console
 
     12:45:29,289 [salt.master    ][INFO    ] Starting Salt worker process 38
     Too many open files

doc/topics/troubleshooting/master.rst

@@ -47,7 +47,7 @@ The salt-master needs at least 2 sockets per host that connects to it, one for
 the Publisher and one for response port. Thus, large installations may, upon
 scaling up the number of minions accessing a given master, encounter:
 
-.. code-block:: bash
+.. code-block:: console
 
     12:45:29,289 [salt.master    ][INFO    ] Starting Salt worker process 38
     Too many open files
@@ -188,7 +188,7 @@ profiling graphs could use `gprof2dot`_, `graphviz`_ and this batch file:
 .. _`gprof2dot`: https://pypi.org/project/gprof2dot
 .. _`graphviz`: https://graphviz.gitlab.io
 
-.. code-block:: bash
+.. code-block:: batch
 
     ::
     :: Converts callgrind* profiler output to *.pdf, via *.dot

doc/topics/troubleshooting/minion.rst

@@ -35,7 +35,7 @@ on various platforms.
 If you have netcat installed, you can check port connectivity from the minion
 with the ``nc`` command:
 
-.. code-block:: bash
+.. code-block:: console
 
     $ nc -v -z salt.master.ip.addr 4505
     Connection to salt.master.ip.addr 4505 port [tcp/unknown] succeeded!
@@ -44,7 +44,7 @@ with the ``nc`` command:
 
 The `Nmap`_ utility can also be used to check if these ports are open:
 
-.. code-block:: bash
+.. code-block:: console
 
     # nmap -sS -q -p 4505-4506 salt.master.ip.addr
 

doc/topics/tutorials/cloud_controller.rst

@@ -342,7 +342,7 @@ to the minions to refresh the pillar to pick up on the change:
 Now, migration routines can be run! To migrate a VM, simply run the Salt Virt
 migrate routine:
 
-.. code-block:: bash
+.. code-block:: console
 
     salt-run virt.migrate centos <new hypervisor>
 

doc/topics/tutorials/gitfs.rst

@@ -1012,7 +1012,7 @@ host key in the ``~/.ssh/known_hosts`` file. If the master is also a minion,
 this can be done using the :mod:`ssh.set_known_host
 <salt.modules.ssh.set_known_host>` function:
 
-.. code-block:: bash
+.. code-block:: console
 
     # salt mymaster ssh.set_known_host user=root hostname=github.com
     mymaster:
@@ -1056,7 +1056,7 @@ Verifying the Fingerprint
 To verify that the correct fingerprint was added, it is a good idea to look it
 up. One way to do this is to use ``nmap``:
 
-.. code-block:: bash
+.. code-block:: console
 
     $ nmap -p 22 github.com --script ssh-hostkey
 
@@ -1138,7 +1138,7 @@ steps to this process:
    all users to fire the event.  Add the following policy to the sudoers file
    on the git server.
 
-   .. code-block:: bash
+   .. code-block:: console
 
        Cmnd_Alias SALT_GIT_HOOK = /bin/salt-call event.fire_master update salt/fileserver/gitfs/update
        Defaults!SALT_GIT_HOOK !requiretty

doc/topics/tutorials/http.rst

@@ -469,8 +469,9 @@ value of match in the return text. In Python terms this looks like:
 
 .. code-block:: python
 
-    if match in html_text:
-        return True
+   def myfunc():
+       if match in html_text:
+           return True
 
 If more complex pattern matching is required, a regular expression can be used
 by specifying a ``match_type``. By default this is set to ``string``, but it

doc/topics/tutorials/intro_scale.rst

@@ -144,7 +144,7 @@ be doubled after each attempt to reconnect (ZeroMQ default behavior).
 
 Lets say the generated random value is 11 seconds (or 11000ms).
 
-.. code-block:: bash
+.. code-block:: console
 
     reconnect 1: wait 11 seconds
     reconnect 2: wait 22 seconds

doc/topics/tutorials/libcloud.rst

@@ -18,17 +18,17 @@ you to manage different cloud resources through a unified and easy to use API. A
 Execution and state modules are available for Compute, DNS, Storage and Load Balancer drivers from Apache Libcloud in
  SaltStack.
 
-* :mod:`libcloud_compute <salt.modules.libcloud_compute>` - Compute - 
+* :mod:`libcloud_compute <salt.modules.libcloud_compute>` - Compute -
     services such as OpenStack Nova, Amazon EC2, Microsoft Azure VMs
-* :mod:`libcloud_dns <salt.modules.libcloud_dns>` - DNS as a Service - 
+* :mod:`libcloud_dns <salt.modules.libcloud_dns>` - DNS as a Service -
     services such as Amazon Route 53 and Zerigo
-* :mod:`libcloud_loadbalancer <salt.modules.libcloud_loadbalancer>` - Load Balancers as a Service - 
+* :mod:`libcloud_loadbalancer <salt.modules.libcloud_loadbalancer>` - Load Balancers as a Service -
     services such as Amazon Elastic Load Balancer and GoGrid LoadBalancers
-* :mod:`libcloud_storage <salt.modules.libcloud_storage>` - Cloud Object Storage and CDN - 
+* :mod:`libcloud_storage <salt.modules.libcloud_storage>` - Cloud Object Storage and CDN -
     services such as Amazon S3 and Rackspace CloudFiles, OpenStack Swift
 
 
-These modules are designed as a way of having a multi-cloud deployment and abstracting simple differences 
+These modules are designed as a way of having a multi-cloud deployment and abstracting simple differences
 between platform to design a high-availability architecture.
 
 The Apache Libcloud functionality is available through both execution modules and Salt states.
@@ -39,11 +39,11 @@ Configuring Drivers
 Drivers can be configured in the Salt Configuration/Minion settings. All libcloud modules expect a list of "profiles" to
 be configured with authentication details for each driver.
 
-Each driver will have a string identifier, these can be found in the libcloud.<api>.types.Provider class 
+Each driver will have a string identifier, these can be found in the libcloud.<api>.types.Provider class
 for each API, https://libcloud.readthedocs.io/en/latest/supported_providers.html
 
 Some drivers require additional parameters, which are documented in the Apache Libcloud documentation. For example,
-GoDaddy DNS expects "`shopper_id`", which is the customer ID. These additional parameters can be added to the profile settings 
+GoDaddy DNS expects "`shopper_id`", which is the customer ID. These additional parameters can be added to the profile settings
 and will be passed directly to the driver instantiation method.
 
 .. code-block:: yaml
@@ -80,25 +80,25 @@ administrators distinguish their purpose.
 Using the execution modules
 ===========================
 
-Amongst over 60 clouds that Apache Libcloud supports, you can add profiles to your Salt configuration to access and control these clouds. 
-Each of the libcloud execution modules exposes the common API methods for controlling Compute, DNS, Load Balancers and Object Storage. 
-To see which functions are supported across specific clouds, see the Libcloud `supported methods 
+Amongst over 60 clouds that Apache Libcloud supports, you can add profiles to your Salt configuration to access and control these clouds.
+Each of the libcloud execution modules exposes the common API methods for controlling Compute, DNS, Load Balancers and Object Storage.
+To see which functions are supported across specific clouds, see the Libcloud `supported methods
 <https://libcloud.readthedocs.io/en/latest/supported_providers.html#supported-methods-block-storage>`_ documentation.
 
 The module documentation explains each of the API methods and how to leverage them.
 
-* :mod:`libcloud_compute <salt.modules.libcloud_compute>` - Compute - 
+* :mod:`libcloud_compute <salt.modules.libcloud_compute>` - Compute -
     services such as OpenStack Nova, Amazon EC2, Microsoft Azure VMs
-* :mod:`libcloud_dns <salt.modules.libcloud_dns>` - DNS as a Service - 
+* :mod:`libcloud_dns <salt.modules.libcloud_dns>` - DNS as a Service -
     services such as Amazon Route 53 and Zerigo
-* :mod:`libcloud_loadbalancer <salt.modules.libcloud_loadbalancer>` - Load Balancers as a Service - 
+* :mod:`libcloud_loadbalancer <salt.modules.libcloud_loadbalancer>` - Load Balancers as a Service -
     services such as Amazon Elastic Load Balancer and GoGrid LoadBalancers
-* :mod:`libcloud_storage <salt.modules.libcloud_storage>` - Cloud Object Storage and CDN - 
+* :mod:`libcloud_storage <salt.modules.libcloud_storage>` - Cloud Object Storage and CDN -
     services such as Amazon S3 and Rackspace CloudFiles, OpenStack Swift
 
-For example, listing buckets in the Google Storage platform: 
+For example, listing buckets in the Google Storage platform:
 
-.. code-block:: bash
+.. code-block:: console
 
     $ salt-call libcloud_storage.list_containers google
 
@@ -123,16 +123,16 @@ such as Google Storage, S3 and OpenStack Swift
 Using the state modules
 =======================
 
-For each configured profile, the assets available in the API (e.g. storage objects, containers, 
+For each configured profile, the assets available in the API (e.g. storage objects, containers,
 DNS records and load balancers) can be deployed via Salt's state system.
 
 The state module documentation explains the specific states that each module supports
 
-* :mod:`libcloud_storage <salt.states.libcloud_storage>` - Cloud Object Storage and CDN 
+* :mod:`libcloud_storage <salt.states.libcloud_storage>` - Cloud Object Storage and CDN
     - services such as Amazon S3 and Rackspace CloudFiles, OpenStack Swift
-* :mod:`libcloud_loadbalancer <salt.states.libcloud_loadbalancer>` - Load Balancers as a Service 
+* :mod:`libcloud_loadbalancer <salt.states.libcloud_loadbalancer>` - Load Balancers as a Service
     - services such as Amazon Elastic Load Balancer and GoGrid LoadBalancers
-* :mod:`libcloud_dns <salt.states.libcloud_dns>` - DNS as a Service 
+* :mod:`libcloud_dns <salt.states.libcloud_dns>` - DNS as a Service
     - services such as Amazon Route 53 and Zerigo
 
 For DNS, the state modules can be used to provide DNS resilience for multiple nameservers, for example:
@@ -223,7 +223,7 @@ Accessing custom arguments in execution modules
 Some cloud providers have additional functionality that can be accessed on top of the base API, for example
 the Google Cloud Engine load balancer service offers the ability to provision load balancers into a specific region.
 
-Looking at the `API documentation <https://libcloud.readthedocs.io/en/latest/loadbalancer/drivers/gce.html#libcloud.loadbalancer.drivers.gce.GCELBDriver.create_balancer>`_, 
+Looking at the `API documentation <https://libcloud.readthedocs.io/en/latest/loadbalancer/drivers/gce.html#libcloud.loadbalancer.drivers.gce.GCELBDriver.create_balancer>`_,
 we can see that it expects an `ex_region` in the `create_balancer` method, so when we execute the salt command, we can add this additional parameter like this:
 
 .. code-block:: bash
@@ -234,11 +234,11 @@ we can see that it expects an `ex_region` in the `create_balancer` method, so wh
 Accessing custom methods in Libcloud drivers
 ============================================
 
-Some cloud APIs have additional methods that are prefixed with `ex_` in Apache Libcloud, these methods 
+Some cloud APIs have additional methods that are prefixed with `ex_` in Apache Libcloud, these methods
 are part of the non-standard API but can still
-be accessed from the Salt modules for `libcloud_storage`, `libcloud_loadbalancer` and `libcloud_dns`. 
-The extra methods are available via the `extra` command, which expects the name of the method as the 
-first argument, the profile as the second and then 
+be accessed from the Salt modules for `libcloud_storage`, `libcloud_loadbalancer` and `libcloud_dns`.
+The extra methods are available via the `extra` command, which expects the name of the method as the
+first argument, the profile as the second and then
 accepts a list of keyword arguments to pass onto the driver method, for example, accessing permissions in Google Storage objects:
 
 .. code-block:: bash

doc/topics/tutorials/packaging_modules.rst

@@ -25,11 +25,11 @@ function:
     from setuptools import setup, find_packages
 
     setup(
-        name=<NAME>,
-        version=<VERSION>,
-        description=<DESC>,
-        author=<AUTHOR>,
-        author_email=<AUTHOR-EMAIL>,
+        name=THE_NAME,
+        version=THE_VERSION,
+        description=THE_DESCRIPTION,
+        author=THE_AUTHOR_NAME,
+        author_email=THE_AUTHOR_EMAIL,
         url=" ... ",
         packages=find_packages(),
         entry_points="""
@@ -39,7 +39,7 @@ function:
         pillar_dirs = <package>.<loader-module>:pillar_dirs
         returner_dirs = <package>.<loader-module>:returner_dirs
         roster_dirs = <package>.<loader-module>:roster_dirs
-        """
+        """,
     )
 
 
@@ -57,36 +57,36 @@ how `<package>/<loader-module>.py` it should look:
 
 
     def engines_dirs():
-	'''
-	yield one path per parent directory of where engines can be found
-	'''
-	yield os.path.join(PKG_DIR, 'engines_1')
-	yield os.path.join(PKG_DIR, 'engines_2')
+        """
+        yield one path per parent directory of where engines can be found
+        """
+        yield os.path.join(PKG_DIR, "engines_1")
+        yield os.path.join(PKG_DIR, "engines_2")
 
 
     def fileserver_dirs():
-	'''
-	yield one path per parent directory of where fileserver modules can be found
-	'''
-	yield os.path.join(PKG_DIR, 'fileserver')
+        """
+        yield one path per parent directory of where fileserver modules can be found
+        """
+        yield os.path.join(PKG_DIR, "fileserver")
 
 
     def pillar_dirs():
-	'''
-	yield one path per parent directory of where external pillar modules can be found
-	'''
-	yield os.path.join(PKG_DIR, 'pillar')
+        """
+        yield one path per parent directory of where external pillar modules can be found
+        """
+        yield os.path.join(PKG_DIR, "pillar")
 
 
     def returner_dirs():
-	'''
-	yield one path per parent directory of where returner modules can be found
-	'''
-	yield os.path.join(PKG_DIR, 'returners')
+        """
+        yield one path per parent directory of where returner modules can be found
+        """
+        yield os.path.join(PKG_DIR, "returners")
 
 
     def roster_dirs():
-	'''
-	yield one path per parent directory of where roster modules can be found
-	'''
-	yield os.path.join(PKG_DIR, 'roster')
+        """
+        yield one path per parent directory of where roster modules can be found
+        """
+        yield os.path.join(PKG_DIR, "roster")

doc/topics/windows/windows-package-manager.rst

@@ -493,7 +493,7 @@ You can get a list of packages installed on the system using
 This will return all software installed on the system whether it is managed by
 Salt or not as shown below:
 
-.. code-block:: bash
+.. code-block:: console
 
     local:
         ----------
@@ -647,7 +647,7 @@ be inside that directory and named ``init.sls``.
 Look at the following example directory structure on a Linux master assuming
 default config settings:
 
-.. code-block:: bash
+.. code-block:: console
 
     srv/
     |---salt/
@@ -932,7 +932,7 @@ the control panel. You can also get this information by installing the package
 manually and then running ``pkg.list_pkgs``. Here's an example of the output
 from ``pkg.list_pkgs``:
 
-.. code-block:: bash
+.. code-block:: console
 
     salt 'test-2008' pkg.list_pkgs
     test-2008