From b427688048fdbee106f910c22ebeb105eb30aa10 Mon Sep 17 00:00:00 2001 From: Pedro Algarvio Date: Thu, 8 Oct 2020 10:54:41 +0100 Subject: [PATCH] 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 | 10 +++ .rstcheck.cfg | 27 ++++++ cicd/jenkins/pre-commit | 2 +- doc/ref/configuration/master.rst | 6 +- doc/ref/modules/index.rst | 2 +- doc/ref/runners/index.rst | 2 +- doc/ref/states/requisites.rst | 2 + doc/ref/states/writing.rst | 53 ++++++----- doc/topics/cloud/aws.rst | 2 +- doc/topics/cloud/cloudstack.rst | 2 +- doc/topics/cloud/config.rst | 66 +++++++------- doc/topics/cloud/dimensiondata.rst | 2 +- doc/topics/cloud/gogrid.rst | 2 +- doc/topics/cloud/joyent.rst | 2 +- doc/topics/cloud/qs.rst | 4 +- doc/topics/cloud/scaleway.rst | 4 +- doc/topics/cloud/troubleshooting.rst | 2 +- doc/topics/cloud/vagrant.rst | 4 +- doc/topics/development/hacking.rst | 2 +- doc/topics/development/package_providers.rst | 8 +- doc/topics/development/tests/integration.rst | 88 +++++++++---------- doc/topics/development/tutorial.rst | 4 +- doc/topics/event/events.rst | 7 +- doc/topics/grains/index.rst | 4 +- doc/topics/installation/eos.rst | 24 ++--- doc/topics/installation/nxos.rst | 10 +-- doc/topics/jinja/index.rst | 6 +- doc/topics/releases/2016.11.0.rst | 2 +- doc/topics/releases/2019.2.0.rst | 4 +- doc/topics/releases/3000.rst | 2 +- doc/topics/releases/releasecandidate.rst | 2 +- doc/topics/spm/dev.rst | 7 +- doc/topics/troubleshooting/index.rst | 2 +- doc/topics/troubleshooting/master.rst | 4 +- doc/topics/troubleshooting/minion.rst | 4 +- doc/topics/tutorials/cloud_controller.rst | 2 +- doc/topics/tutorials/gitfs.rst | 6 +- doc/topics/tutorials/http.rst | 5 +- doc/topics/tutorials/intro_scale.rst | 2 +- doc/topics/tutorials/libcloud.rst | 50 +++++------ doc/topics/tutorials/packaging_modules.rst | 54 ++++++------ .../windows/windows-package-manager.rst | 6 +- 42 files changed, 274 insertions(+), 225 deletions(-) create mode 100644 .rstcheck.cfg diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 881f997ea8e..c474b7df3e2 100644 --- a/.pre-commit-config.yaml +++ b/.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: diff --git a/.rstcheck.cfg b/.rstcheck.cfg new file mode 100644 index 00000000000..a2c5731b9e1 --- /dev/null +++ b/.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 diff --git a/cicd/jenkins/pre-commit b/cicd/jenkins/pre-commit index a8c873abdaa..c656c0190b2 100644 --- a/cicd/jenkins/pre-commit +++ b/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( diff --git a/doc/ref/configuration/master.rst b/doc/ref/configuration/master.rst index 84a9ba3568b..ac73bf023a5 100644 --- a/doc/ref/configuration/master.rst +++ b/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 `. 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) diff --git a/doc/ref/modules/index.rst b/doc/ref/modules/index.rst index faaab769e82..9d212518b3f 100644 --- a/doc/ref/modules/index.rst +++ b/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%) diff --git a/doc/ref/runners/index.rst b/doc/ref/runners/index.rst index 5eedd3dc530..d8032eb0e20 100644 --- a/doc/ref/runners/index.rst +++ b/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) diff --git a/doc/ref/states/requisites.rst b/doc/ref/states/requisites.rst index 11e5c9f1881..5da19657c49 100644 --- a/doc/ref/states/requisites.rst +++ b/doc/ref/states/requisites.rst @@ -363,6 +363,8 @@ shown in json for clarity: } } +.. code-block:: json + { "local": { "pkgrepo_|-salt-minion_|-salt-minion_|-managed": { diff --git a/doc/ref/states/writing.rst b/doc/ref/states/writing.rst index e824825153b..e1aaad596fe 100644 --- a/doc/ref/states/writing.rst +++ b/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. diff --git a/doc/topics/cloud/aws.rst b/doc/topics/cloud/aws.rst index 86ec6e7ecba..76833f41f53 100644 --- a/doc/topics/cloud/aws.rst +++ b/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.. diff --git a/doc/topics/cloud/cloudstack.rst b/doc/topics/cloud/cloudstack.rst index aa562eab15c..f67857e6135 100644 --- a/doc/topics/cloud/cloudstack.rst +++ b/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: diff --git a/doc/topics/cloud/config.rst b/doc/topics/cloud/config.rst index 828540e3b7c..ea1053211c4 100644 --- a/doc/topics/cloud/config.rst +++ b/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", + } + ], + } } diff --git a/doc/topics/cloud/dimensiondata.rst b/doc/topics/cloud/dimensiondata.rst index 4a0b3180a2e..cebc2ed46d5 100644 --- a/doc/topics/cloud/dimensiondata.rst +++ b/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: diff --git a/doc/topics/cloud/gogrid.rst b/doc/topics/cloud/gogrid.rst index 59deb117c7f..bea1c59de4f 100644 --- a/doc/topics/cloud/gogrid.rst +++ b/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: diff --git a/doc/topics/cloud/joyent.rst b/doc/topics/cloud/joyent.rst index 4541e0aff47..21efda85729 100644 --- a/doc/topics/cloud/joyent.rst +++ b/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: diff --git a/doc/topics/cloud/qs.rst b/doc/topics/cloud/qs.rst index 9b37c3ea16f..50606316f4b 100644 --- a/doc/topics/cloud/qs.rst +++ b/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 # my-ec2 in the previous example salt-cloud --list-images @@ -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 ... diff --git a/doc/topics/cloud/scaleway.rst b/doc/topics/cloud/scaleway.rst index 009e29515f7..bb4fb70a292 100644 --- a/doc/topics/cloud/scaleway.rst +++ b/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 diff --git a/doc/topics/cloud/troubleshooting.rst b/doc/topics/cloud/troubleshooting.rst index 7924c9fe9c4..983f0e475f3 100644 --- a/doc/topics/cloud/troubleshooting.rst +++ b/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) diff --git a/doc/topics/cloud/vagrant.rst b/doc/topics/cloud/vagrant.rst index bcae202c9e7..242ef459732 100644 --- a/doc/topics/cloud/vagrant.rst +++ b/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 ... ] diff --git a/doc/topics/development/hacking.rst b/doc/topics/development/hacking.rst index 4364681e315..b7363b82fbb 100644 --- a/doc/topics/development/hacking.rst +++ b/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" diff --git a/doc/topics/development/package_providers.rst b/doc/topics/development/package_providers.rst index 12a931aaad1..f0e59d310c4 100644 --- a/doc/topics/development/package_providers.rst +++ b/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', diff --git a/doc/topics/development/tests/integration.rst b/doc/topics/development/tests/integration.rst index 4eb2bb9a8a7..6d9d613831d 100644 --- a/doc/topics/development/tests/integration.rst +++ b/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 diff --git a/doc/topics/development/tutorial.rst b/doc/topics/development/tutorial.rst index d235454062d..38e8b01ec0a 100644 --- a/doc/topics/development/tutorial.rst +++ b/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': @@ -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/ diff --git a/doc/topics/event/events.rst b/doc/topics/event/events.rst index c7a76f6e630..21a4329039c 100644 --- a/doc/topics/event/events.rst +++ b/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 diff --git a/doc/topics/grains/index.rst b/doc/topics/grains/index.rst index 92a94f61fb1..3eeabfa1659 100644 --- a/doc/topics/grains/index.rst +++ b/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: diff --git a/doc/topics/installation/eos.rst b/doc/topics/installation/eos.rst index c8c7787be70..6e0cc5fb125 100644 --- a/doc/topics/installation/eos.rst +++ b/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`. @@ -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 diff --git a/doc/topics/installation/nxos.rst b/doc/topics/installation/nxos.rst index cb92f28e536..743328c0919 100644 --- a/doc/topics/installation/nxos.rst +++ b/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: export https_proxy=https://proxy.yourdomain.com: diff --git a/doc/topics/jinja/index.rst b/doc/topics/jinja/index.rst index 2139c5c55e0..e16537a98fa 100644 --- a/doc/topics/jinja/index.rst +++ b/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 [...] diff --git a/doc/topics/releases/2016.11.0.rst b/doc/topics/releases/2016.11.0.rst index aae3c8c0a30..2aad664eca9 100644 --- a/doc/topics/releases/2016.11.0.rst +++ b/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: diff --git a/doc/topics/releases/2019.2.0.rst b/doc/topics/releases/2019.2.0.rst index f630b4ec233..1d3db429653 100644 --- a/doc/topics/releases/2019.2.0.rst +++ b/doc/topics/releases/2019.2.0.rst @@ -713,7 +713,7 @@ Alternatively, the newly-added :py:func:`pkg.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 ` (either directly, or implicitly via a :ref:`netapi module `) need to update their code to use ``tgt_type``. -.. code-block:: python +.. code-block:: pycon >>> import salt.client >>> local = salt.client.LocalClient() diff --git a/doc/topics/releases/3000.rst b/doc/topics/releases/3000.rst index eb5af5e9199..70cd6d16fa3 100644 --- a/doc/topics/releases/3000.rst +++ b/doc/topics/releases/3000.rst @@ -292,7 +292,7 @@ A new :py:func:`state ` 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: diff --git a/doc/topics/releases/releasecandidate.rst b/doc/topics/releases/releasecandidate.rst index 53efd449e38..a637f5724b1 100644 --- a/doc/topics/releases/releasecandidate.rst +++ b/doc/topics/releases/releasecandidate.rst @@ -115,7 +115,7 @@ Then install salt using the following command: .. code-block:: bash - sudo pip install salt== + sudo pip install salt==$rc_tag_version For example for the 3002rc1 release: diff --git a/doc/topics/spm/dev.rst b/doc/topics/spm/dev.rst index e96355dca2e..017b1de002a 100644 --- a/doc/topics/spm/dev.rst +++ b/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 diff --git a/doc/topics/troubleshooting/index.rst b/doc/topics/troubleshooting/index.rst index 616a5b457c7..9838c28f6e1 100644 --- a/doc/topics/troubleshooting/index.rst +++ b/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 diff --git a/doc/topics/troubleshooting/master.rst b/doc/topics/troubleshooting/master.rst index cb0a12bf8ca..889bd668e4b 100644 --- a/doc/topics/troubleshooting/master.rst +++ b/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 diff --git a/doc/topics/troubleshooting/minion.rst b/doc/topics/troubleshooting/minion.rst index f5ed86339bf..e58e42f582d 100644 --- a/doc/topics/troubleshooting/minion.rst +++ b/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 diff --git a/doc/topics/tutorials/cloud_controller.rst b/doc/topics/tutorials/cloud_controller.rst index dccb4f4ec7d..3f42a2204bb 100644 --- a/doc/topics/tutorials/cloud_controller.rst +++ b/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 diff --git a/doc/topics/tutorials/gitfs.rst b/doc/topics/tutorials/gitfs.rst index 0de69b077b2..df51186d0c2 100644 --- a/doc/topics/tutorials/gitfs.rst +++ b/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 ` 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 diff --git a/doc/topics/tutorials/http.rst b/doc/topics/tutorials/http.rst index 31d0a5cdac8..54a2e1e8856 100644 --- a/doc/topics/tutorials/http.rst +++ b/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 diff --git a/doc/topics/tutorials/intro_scale.rst b/doc/topics/tutorials/intro_scale.rst index 80338fd7af1..371200b64e7 100644 --- a/doc/topics/tutorials/intro_scale.rst +++ b/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 diff --git a/doc/topics/tutorials/libcloud.rst b/doc/topics/tutorials/libcloud.rst index d4abe00877e..4f9be2bde15 100644 --- a/doc/topics/tutorials/libcloud.rst +++ b/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 ` - Compute - +* :mod:`libcloud_compute ` - Compute - services such as OpenStack Nova, Amazon EC2, Microsoft Azure VMs -* :mod:`libcloud_dns ` - DNS as a Service - +* :mod:`libcloud_dns ` - DNS as a Service - services such as Amazon Route 53 and Zerigo -* :mod:`libcloud_loadbalancer ` - Load Balancers as a Service - +* :mod:`libcloud_loadbalancer ` - Load Balancers as a Service - services such as Amazon Elastic Load Balancer and GoGrid LoadBalancers -* :mod:`libcloud_storage ` - Cloud Object Storage and CDN - +* :mod:`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..types.Provider class +Each driver will have a string identifier, these can be found in the libcloud..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 `_ documentation. The module documentation explains each of the API methods and how to leverage them. -* :mod:`libcloud_compute ` - Compute - +* :mod:`libcloud_compute ` - Compute - services such as OpenStack Nova, Amazon EC2, Microsoft Azure VMs -* :mod:`libcloud_dns ` - DNS as a Service - +* :mod:`libcloud_dns ` - DNS as a Service - services such as Amazon Route 53 and Zerigo -* :mod:`libcloud_loadbalancer ` - Load Balancers as a Service - +* :mod:`libcloud_loadbalancer ` - Load Balancers as a Service - services such as Amazon Elastic Load Balancer and GoGrid LoadBalancers -* :mod:`libcloud_storage ` - Cloud Object Storage and CDN - +* :mod:`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 ` - Cloud Object Storage and CDN +* :mod:`libcloud_storage ` - Cloud Object Storage and CDN - services such as Amazon S3 and Rackspace CloudFiles, OpenStack Swift -* :mod:`libcloud_loadbalancer ` - Load Balancers as a Service +* :mod:`libcloud_loadbalancer ` - Load Balancers as a Service - services such as Amazon Elastic Load Balancer and GoGrid LoadBalancers -* :mod:`libcloud_dns ` - DNS as a Service +* :mod:`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 `_, +Looking at the `API documentation `_, 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 diff --git a/doc/topics/tutorials/packaging_modules.rst b/doc/topics/tutorials/packaging_modules.rst index ba7d327e96e..8014b3e4656 100644 --- a/doc/topics/tutorials/packaging_modules.rst +++ b/doc/topics/tutorials/packaging_modules.rst @@ -25,11 +25,11 @@ function: from setuptools import setup, find_packages setup( - name=, - version=, - description=, - author=, - 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 = .:pillar_dirs returner_dirs = .:returner_dirs roster_dirs = .:roster_dirs - """ + """, ) @@ -57,36 +57,36 @@ how `/.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") diff --git a/doc/topics/windows/windows-package-manager.rst b/doc/topics/windows/windows-package-manager.rst index 8c85ef422ac..7cf53aee028 100644 --- a/doc/topics/windows/windows-package-manager.rst +++ b/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