Merge pull request #50504 from terminalmage/develop-docs

Set jenkins docs job to treat any warnings as errors (develop branch)
saltstack · Nov 14, 2018 · 065e33a · 065e33a
2 parents 4bd0d1d + 5e734c4
commit 065e33a
Show file tree

Hide file tree

Showing 37 changed files with 406 additions and 314 deletions.
diff --git a/.ci/docs b/.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})"
         }
     }

diff --git a/doc/conf.py b/doc/conf.py
@@ -271,9 +271,10 @@ def inner(fn, *iargs, **ikwargs):
 
 # < --- START do not merge these settings to other branches START ---> #
 build_type = 'develop'  # latest, previous, develop, next
-release = version  # version, latest_release, previous_release
 # < --- END do not merge these settings to other branches END ---> #
 
+release = latest_release if build_type == 'develop' else version
+
 # Set google custom search engine
 
 if release == latest_release:
@@ -308,7 +309,7 @@ def inner(fn, *iargs, **ikwargs):
     'sphinx.ext.intersphinx',
     'httpdomain',
     'youtube',
-    'saltautodoc', # Must be AFTER autodoc
+    #'saltautodoc', # Must be AFTER autodoc
     'shorturls',
 ]
 

diff --git a/doc/ref/clients/index.rst b/doc/ref/clients/index.rst
@@ -98,13 +98,13 @@ RunnerClient
 ------------
 
 .. autoclass:: salt.runner.RunnerClient
-    :members: cmd, async, cmd_sync, cmd_async
+    :members: cmd, asynchronous, cmd_sync, cmd_async
 
 WheelClient
 -----------
 
 .. autoclass:: salt.wheel.WheelClient
-    :members: cmd, async, cmd_sync, cmd_async
+    :members: cmd, asynchronous, cmd_sync, cmd_async
 
 CloudClient
 -----------

diff --git a/doc/ref/engines/all/index.rst b/doc/ref/engines/all/index.rst
@@ -16,7 +16,7 @@ engine modules
     ircbot
     junos_syslog
     logentries
-    logstash
+    logstash_engine
     napalm_syslog
     reactor
     redis_sentinel

diff --git a/doc/ref/engines/all/salt.engines.logstash.rst b/doc/ref/engines/all/salt.engines.logstash.rst
diff --git a/doc/ref/engines/all/salt.engines.logstash_engine.rst b/doc/ref/engines/all/salt.engines.logstash_engine.rst
@@ -0,0 +1,6 @@
+============================
+salt.engines.logstash_engine
+============================
+
+.. automodule:: salt.engines.logstash_engine
+    :members:
diff --git a/doc/ref/states/requisites.rst b/doc/ref/states/requisites.rst
@@ -581,7 +581,7 @@ In the following example, Salt will not try to manage the nginx service or any
 configuration files unless the nginx package is installed because of the ``pkg:
 nginx`` requisite.
 
-.. code-block:: yaml
+.. code-block:: jinja
 
     nginx:
       pkg.installed: []

diff --git a/doc/ref/tops/all/salt.tops.varstack.rst b/doc/ref/tops/all/salt.tops.varstack.rst
diff --git a/doc/ref/tops/all/salt.tops.varstack_top.rst b/doc/ref/tops/all/salt.tops.varstack_top.rst
@@ -0,0 +1,6 @@
+======================
+salt.tops.varstack_top
+======================
+
+.. automodule:: salt.tops.varstack_top
+    :members:
diff --git a/doc/topics/index.rst b/doc/topics/index.rst
@@ -84,8 +84,11 @@ versatile as it is practical, suitable for any network.
 
 Open
 ====
+
 Salt is developed under the `Apache 2.0 license`_, and can be used for
 open and proprietary projects. Please submit your expansions back to
 the Salt project so that we can all benefit together as Salt grows.
 Please feel free to sprinkle Salt around your systems and let the
 deliciousness come forth.
+
+.. _`Apache 2.0 license`: http://www.apache.org/licenses/LICENSE-2.0.html
diff --git a/doc/topics/releases/2014.7.0.rst b/doc/topics/releases/2014.7.0.rst
@@ -54,9 +54,6 @@ release.
 Simply stated, users running Salt with RAET should expect some hiccups as we
 hammer out the update. This is a BETA release of Salt RAET.
 
-For information about how to use Salt with RAET please see the
-:ref:`tutorial <raet>`.
-
 Salt SSH Enhancements
 =====================
 

diff --git a/doc/topics/releases/2018.3.3.rst b/doc/topics/releases/2018.3.3.rst
@@ -92,7 +92,7 @@ Example:
     cmd.run 'echo '\''h=\"baz\"'\''' runas=macuser
 
 Changelog for v2018.3.2..v2018.3.3
-=================================================================
+==================================
 
 *Generated at: 2018-09-21 17:45:27 UTC*
 
@@ -507,7 +507,7 @@ Changelog for v2018.3.2..v2018.3.3
 
   * 3d26affa10 Fix remaining file state integration tests (py3)
 
-* **PR** `#49171`_: (`Ch3LL`_) [2018.3.3] cherry pick `#49103`_ 
+* **PR** `#49171`_: (`Ch3LL`_) [2018.3.3] cherry pick `#49103`_
   @ *2018-08-17 20:23:32 UTC*
 
   * **PR** `#49103`_: (`dwoz`_) Install the launcher so we can execute py files (refs: `#49171`_)
@@ -1630,7 +1630,7 @@ Changelog for v2018.3.2..v2018.3.3
 
 * **ISSUE** `#46896`_: (`Poil`_) Proxy + file.managed => Comment: Failed to cache xxx invalid arguments to setopt (refs: `#48754`_)
 
-* **PR** `#48754`_: (`lomeroe`_) send proxy/ca_cert parameters as strings (not unicode) to tornado httpclient 
+* **PR** `#48754`_: (`lomeroe`_) send proxy/ca_cert parameters as strings (not unicode) to tornado httpclient
   @ *2018-07-25 14:55:42 UTC*
 
   * 030c921914 Merge pull request `#48754`_ from lomeroe/fix-tornado-proxy
@@ -3075,7 +3075,7 @@ Changelog for v2018.3.2..v2018.3.3
 
   * dae65da256 Merge branch '2018.3.1' into '2018.3'
 
-* **PR** `#48186`_: (`rallytime`_) Add autodoc module for saltcheck.py 
+* **PR** `#48186`_: (`rallytime`_) Add autodoc module for saltcheck.py
   @ *2018-06-19 19:03:55 UTC*
 
   * 5b4897f050 Merge pull request `#48186`_ from rallytime/saltcheck-docs
@@ -3362,11 +3362,11 @@ Changelog for v2018.3.2..v2018.3.3
 * **PR** `#48109`_: (`rallytime`_) Back-port `#47851`_ to 2018.3
   @ *2018-06-14 13:09:04 UTC*
 
-  * **PR** `#47851`_: (`rares-pop`_) Fixup! add master.py:FileserverUpdate **kwargs (refs: `#48109`_)
+  * **PR** `#47851`_: (`rares-pop`_) Fixup! add master.py:FileserverUpdate \*\*kwargs (refs: `#48109`_)
 
   * 2902ee0b14 Merge pull request `#48109`_ from rallytime/bp-47851
 
-  * e9dc30bf8e Fixup! add master.py:FileserverUpdate **kwargs
+  * e9dc30bf8e Fixup! add master.py:FileserverUpdate \*\*kwargs
 
 * **ISSUE** `#47925`_: (`JonGriggs`_) GitFS looking for files in the master branch only (refs: `#47943`_)
 
@@ -3377,7 +3377,7 @@ Changelog for v2018.3.2..v2018.3.3
 
   * 534e1a7100 Merge branch '2018.3' into issue47925
 
-* **PR** `#48089`_: (`rallytime`_) Update release versions for the 2018.3 branch 
+* **PR** `#48089`_: (`rallytime`_) Update release versions for the 2018.3 branch
   @ *2018-06-13 14:03:44 UTC*
 
   * 9e1d0040e4 Merge pull request `#48089`_ from rallytime/update_version_doc_2018.3

diff --git a/doc/topics/releases/neon.rst b/doc/topics/releases/neon.rst
@@ -37,7 +37,7 @@ Usage
 
 Example file system layout:
 
-.. code-block:: txt
+.. code-block:: text
 
     /srv/salt/apache/
         init.sls
@@ -47,10 +47,11 @@ Example file system layout:
             config.tst
             deployment_validation.tst
 
-Tests can be run for each state by name, for all apache/saltcheck/*.tst files, or for all states
-assigned to the minion in top.sls. Tests may also be created with no associated state. These tests
-will be run through the use of ``saltcheck.run_state_tests``, but will not be automatically run
-by ``saltcheck.run_highstate_tests``.
+Tests can be run for each state by name, for all ``apache/saltcheck/*.tst`` files,
+or for all states assigned to the minion in top.sls. Tests may also be created
+with no associated state. These tests will be run through the use of
+``saltcheck.run_state_tests``, but will not be automatically run by
+``saltcheck.run_highstate_tests``.
 
 .. code-block:: bash
 

diff --git a/salt/cloud/clouds/oneandone.py b/salt/cloud/clouds/oneandone.py
@@ -99,6 +99,7 @@
 
     sudo salt-cloud -f create_firewall_policy oneandone name='1salttest'
     description='salt_test_desc' rules='[{"protocol":"TCP", "port":"80", "description":"salt_fw_rule_desc"}]'
+
 List baremetal models
 
 .. code-block:: bash

diff --git a/salt/modules/bluecoat_sslv.py b/salt/modules/bluecoat_sslv.py
@@ -2,7 +2,7 @@
 '''
 Module to provide Blue Coat SSL Visibility compatibility to Salt.
 
-:codeauthor: :email:`Spencer Ervin <[email protected]>`
+:codeauthor: Spencer Ervin <[email protected]>
 :maturity:   new
 :depends:    none
 :platform:   unix
@@ -16,7 +16,7 @@
 Options passed into opts will be ignored if options are passed into pillar.
 
 .. seealso::
-    :prox:`Blue Coat SSL Visibility Proxy Module <salt.proxy.bluecoat_sslv>`
+    :py:mod:`Blue Coat SSL Visibility Proxy Module <salt.proxy.bluecoat_sslv>`
 
 About
 =====

diff --git a/salt/modules/boto3_elasticache.py b/salt/modules/boto3_elasticache.py
@@ -993,6 +993,7 @@ def modify_cache_parameter_group(name, region=None, key=None, keyid=None, profil
         update.  At least one parameter/value pair is required.
 
     .. code-block:: yaml
+
         ParameterNameValues:
         - ParameterName: timeout
           # Amazon requires ALL VALUES to be strings...

diff --git a/salt/modules/dracr.py b/salt/modules/dracr.py
@@ -1,6 +1,6 @@
 # -*- coding: utf-8 -*-
 '''
-Manage Dell DRAC.
+Manage Dell DRAC
 
 .. versionadded:: 2015.8.2
 '''
@@ -154,6 +154,7 @@ def __execute_ret(command, host=None,
 def get_property(host=None, admin_username=None, admin_password=None, property=None):
     '''
     .. versionadded:: Fluorine
+
     Return specific property
 
     host
@@ -185,6 +186,7 @@ def get_property(host=None, admin_username=None, admin_password=None, property=N
 def set_property(host=None, admin_username=None, admin_password=None, property=None, value=None):
     '''
     .. versionadded:: Fluorine
+
     Set specific property
 
     host
@@ -221,7 +223,8 @@ def set_property(host=None, admin_username=None, admin_password=None, property=N
 def ensure_property_set(host=None, admin_username=None, admin_password=None, property=None, value=None):
     '''
     .. versionadded:: Fluorine
-    Ensure that property is set to specific value.
+
+    Ensure that property is set to specific value
 
     host
         The chassis host.

diff --git a/salt/modules/nxos.py b/salt/modules/nxos.py
@@ -5,10 +5,14 @@
 .. versionadded:: 2016.11.0
 
 This module supports execution using a Proxy Minion or Native Minion:
-1) Proxy Minion: Connect over SSH or NX-API HTTP(S).
-   See :mod:`salt.proxy.nxos <salt.proxy.nxos>` for proxy minion setup details.
-2) Native Minion: Connect over NX-API Unix Domain Socket (UDS).
-   Install the minion inside the GuestShell running on the NX-OS device.
+
+- Proxy Minion: Connect over SSH or NX-API HTTP(S).
+
+  - See :mod:`salt.proxy.nxos <salt.proxy.nxos>` for proxy minion setup details.
+
+- Native Minion: Connect over NX-API Unix Domain Socket (UDS).
+
+  - Install the minion inside the GuestShell running on the NX-OS device.
 
 :maturity:   new
 :platform:   nxos
@@ -45,22 +49,26 @@
       cookie: 'username'
       no_save_config: True
 
-cookie
-    Use the option to override the default cookie 'admin:local' when
-    connecting over UDS and use 'username:local' instead. This is needed when
-    running the salt-minion in the GuestShell using a non-admin user.
+``cookie``
+
+- Use the option to override the default cookie 'admin:local' when connecting
+  over UDS and use 'username:local' instead. This is needed when running the
+  salt-minion in the GuestShell using a non-admin user.
+
+- This option is ignored for SSH and NX-API Proxy minions.
+
+``no_save_config``
+
+- If False, 'copy running-config starting-config' is issues for every
+  configuration command.
 
-    This option is ignored for SSH and NX-API Proxy minions.
+- If True, Running config is not saved to startup config
 
-no_save_config:
-    If False, 'copy running-config starting-config' is issues for every
-        configuration command.
-    If True, Running config is not saved to startup config
-    Default: False
+- Default: False
 
-    The recommended approach is to use the `save_running_config` function
-    instead of this option to improve performance.  The default behavior
-    controlled by this option is preserved for backwards compatibility.
+- The recommended approach is to use the `save_running_config` function instead
+  of this option to improve performance.  The default behavior controlled by
+  this option is preserved for backwards compatibility.
 
 
 The APIs defined in this execution module can also be executed using
@@ -75,13 +83,17 @@
     The functions in this module can be executed using either of the
     following syntactic forms.
 
-    salt '*' nxos.cmd <function>
-    salt '*' nxos.cmd get_user username=admin
+    .. code-block:: bash
+
+        salt '*' nxos.cmd <function>
+        salt '*' nxos.cmd get_user username=admin
 
     or
 
-    salt '*' nxos.<function>
-    salt '*' nxos.get_user username=admin
+    .. code-block:: bash
+
+        salt '*' nxos.<function>
+        salt '*' nxos.get_user username=admin
 
     The nxos.cmd <function> syntax is preserved for backwards compatibility.
 '''

diff --git a/salt/modules/saltcheck.py b/salt/modules/saltcheck.py
@@ -24,7 +24,7 @@
 
 Example file system layout:
 
-.. code-block:: txt
+.. code-block:: text
 
     /srv/salt/apache/
         init.sls
@@ -34,10 +34,11 @@
             config.tst
             deployment_validation.tst
 
-Tests can be run for each state by name, for all apache/saltcheck/*.tst files, or for all states
-assigned to the minion in top.sls. Tests may also be created with no associated state. These tests
-will be run through the use of ``saltcheck.run_state_tests``, but will not be automatically run
-by ``saltcheck.run_highstate_tests``.
+Tests can be run for each state by name, for all ``apache/saltcheck/*.tst``
+files, or for all states assigned to the minion in top.sls. Tests may also be
+created with no associated state. These tests will be run through the use of
+``saltcheck.run_state_tests``, but will not be automatically run by
+``saltcheck.run_highstate_tests``.
 
 .. code-block:: bash