Merge pull request #50503 from terminalmage/2018.3-docs

Set jenkins docs job to treat any warnings as errors (2018.3 branch)

.ci/docs

@@ -29,7 +29,7 @@ pipeline {
         }
         stage('build') {
             steps {
-                sh 'eval "$(pyenv init -)"; make -C doc clean html'
+                sh 'eval "$(pyenv init -)"; make SPHINXOPTS="-W" -C doc clean html'
             }
         }
     }
@@ -48,8 +48,8 @@ pipeline {
                 description: 'The docs job has failed',
                 status: 'FAILURE',
                 context: "jenkins/pr/docs"
-            slackSend channel: "#jenkins-prod-pr", 
-                color: '#FF0000', 
+            slackSend channel: "#jenkins-prod-pr",
+                color: '#FF0000',
                 message: "FAILED: PR-Job: '${env.JOB_NAME} [${env.BUILD_NUMBER}]' (${env.BUILD_URL})"
         }
     }

doc/conf.py

@@ -302,7 +302,7 @@ extensions = [
     'sphinx.ext.intersphinx',
     'httpdomain',
     'youtube',
-    'saltautodoc', # Must be AFTER autodoc
+    #'saltautodoc', # Must be AFTER autodoc
     'shorturls',
 ]
 

doc/ref/engines/all/index.rst

@@ -16,7 +16,7 @@ engine modules
     ircbot
     junos_syslog
     logentries
-    logstash
+    logstash_engine
     napalm_syslog
     reactor
     redis_sentinel

doc/ref/engines/all/salt.engines.logstash.rst

@@ -1,6 +0,0 @@
-=====================
-salt.engines.logstash
-=====================
-
-.. automodule:: salt.engines.logstash
-    :members:

doc/ref/engines/all/salt.engines.logstash_engine.rst

@@ -0,0 +1,6 @@
+============================
+salt.engines.logstash_engine
+============================
+
+.. automodule:: salt.engines.logstash_engine
+    :members:

salt/states/alternatives.py

@@ -202,6 +202,12 @@ def set_(name, path):
     path
         is the location of one of the alternative target files.
         (e.g. /usr/bin/less)
+
+    .. code-block:: yaml
+
+        foo:
+          alternatives.set:
+            - path: /usr/bin/foo-2.0
     '''
     ret = {'name': name,
            'path': path,

salt/states/eselect.py

@@ -5,11 +5,6 @@ Management of Gentoo configuration using eselect
 
 A state module to manage Gentoo configuration via eselect
 
-.. code-block:: yaml
-
-    profile:
-        eselect.set:
-            target: hardened/linux/amd64
 '''
 
 # Import Python libs
@@ -44,6 +39,11 @@ def set_(name, target, module_parameter=None, action_parameter=None):
     action_parameter
         additional params passed to the defined action
 
+    .. code-block:: yaml
+
+        profile:
+          eselect.set:
+            - target: hardened/linux/amd64
     '''
     ret = {'changes': {},
            'comment': '',

salt/states/etcd_mod.py

@@ -126,7 +126,6 @@ __virtualname__ = 'etcd'
 # Function aliases
 __func_alias__ = {
     'set_': 'set',
-    'rm_': 'rm'
 }
 
 # Import third party libs
@@ -147,12 +146,13 @@ def __virtual__():
 
 def set_(name, value, profile=None, **kwargs):
     '''
-    Set a key in etcd and can be called as ``set``.
+    Set a key in etcd
 
     name
         The etcd key name, for example: ``/foo/bar/baz``.
     value
         The value the key should contain.
+
     profile
         Optional, defaults to ``None``. Sets the etcd profile to use which has
         been defined in the Salt Master config.
@@ -263,14 +263,16 @@ def directory(name, profile=None, **kwargs):
     return rtn
 
 
-def rm_(name, recurse=False, profile=None, **kwargs):
+def rm(name, recurse=False, profile=None, **kwargs):
     '''
-    Deletes a key from etcd. This function is also aliased as ``rm``.
+    Deletes a key from etcd
 
     name
         The etcd key name to remove, for example ``/foo/bar/baz``.
+
     recurse
         Optional, defaults to ``False``. If ``True`` performs a recursive delete.
+
     profile
         Optional, defaults to ``None``. Sets the etcd profile to use which has
         been defined in the Salt Master config.
@@ -353,7 +355,7 @@ def mod_watch(name, **kwargs):
 
     # Watch to rm etcd key
     if kwargs.get('sfun') in ['wait_rm_key', 'wait_rm']:
-        return rm_(
+        return rm(
             name,
             kwargs.get('profile'))
 

salt/states/logrotate.py

@@ -62,20 +62,20 @@ def set_(name, key, value, setting=None, conf_file=_DEFAULT_CONF):
     .. code-block:: yaml
 
         logrotate-rotate:
-            logrotate.set:
-                - key: rotate
-                - value: 2
+          logrotate.set:
+            - key: rotate
+            - value: 2
 
     Example of usage specifying all available arguments:
 
     .. code-block:: yaml
 
         logrotate-wtmp-rotate:
-            logrotate.set:
-                - key: /var/log/wtmp
-                - value: rotate
-                - setting: 2
-                - conf_file: /etc/logrotate.conf
+          logrotate.set:
+            - key: /var/log/wtmp
+            - value: rotate
+            - setting: 2
+            - conf_file: /etc/logrotate.conf
     '''
     ret = {'name': name,
            'changes': dict(),

salt/states/zone.py

@@ -127,7 +127,6 @@ log = logging.getLogger(__name__)
 
 __func_alias__ = {
     'import_': 'import',
-    'export_': 'export',
 }
 
 # Define the state's virtual name
@@ -623,7 +622,7 @@ def halted(name, graceful=True):
     return ret
 
 
-def export_(name, path, replace=False):
+def export(name, path, replace=False):
     '''
     Export a zones configuration
 
@@ -760,6 +759,11 @@ def import_(name, path, mode='import', nodataset=False, brand_opts=None):
         ``install``: will import and then try to install the zone
         ``attach``: will import and then try to attach of the zone
 
+    .. code-block:: yaml
+
+        omipkg1:
+          zone.import:
+            - path: /foo/bar/baz
     '''
     ret = {'name': name,
            'changes': {},