Fix all Sphinx warnings

Well, all but one, which we expect to see

doc/.scripts/compile-translation-catalogs

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
 '''
-    :codeauthor: :email:`Pedro Algarvio ([email protected])`
+    :codeauthor: Pedro Algarvio ([email protected])
 
 
     compile-translation-catalogs

doc/.scripts/download-translation-catalog

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
 '''
-    :codeauthor: :email:`Pedro Algarvio ([email protected])`
+    :codeauthor: Pedro Algarvio ([email protected])
 
 
     download-translation-catalog

doc/.scripts/setup-transifex-config

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
 '''
-    :codeauthor: :email:`Pedro Algarvio ([email protected])`
+    :codeauthor: Pedro Algarvio ([email protected])
 
 
     setup-transifex-config

doc/.scripts/update-transifex-source-translations

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
 '''
-    :codeauthor: :email:`Pedro Algarvio ([email protected])`
+    :codeauthor: Pedro Algarvio ([email protected])
 
 
     update-transifex-source-translations

doc/_ext/saltautodoc.py

@@ -1,6 +1,6 @@
 # -*- coding: utf-8 -*-
 '''
-    :codeauthor: :email:`Pedro Algarvio ([email protected])`
+    :codeauthor: Pedro Algarvio ([email protected])
 
 
     saltautodoc.py

doc/conf.py

@@ -106,6 +106,7 @@ def next(self):
 
     'tornado',
     'tornado.concurrent',
+    'tornado.escape',
     'tornado.gen',
     'tornado.httpclient',
     'tornado.httpserver',
@@ -137,8 +138,8 @@ def next(self):
     'pymongo',
     'rabbitmq_server',
     'redis',
-    'requests',
-    'requests.exceptions',
+    #'requests',
+    #'requests.exceptions',
     'rpm',
     'rpmUtils',
     'rpmUtils.arch',
@@ -237,8 +238,7 @@ def inner(fn, *iargs, **ikwargs):
 
 # ----- Intersphinx Settings ------------------------------------------------>
 intersphinx_mapping = {
-        'python2': ('http://docs.python.org/2', None),
-        'python3': ('http://docs.python.org/3', None)
+    'python': ('https://docs.python.org/3', None)
 }
 # <---- Intersphinx Settings -------------------------------------------------
 
@@ -357,9 +357,8 @@ def inner(fn, *iargs, **ikwargs):
 # A shortcut for linking to tickets on the GitHub issue tracker
 extlinks = {
     'blob': ('https://github.com/saltstack/salt/blob/%s/%%s' % 'develop', None),
-    'download': ('https://cloud.github.com/downloads/saltstack/salt/%s', None),
-    'issue': ('https://github.com/saltstack/salt/issues/%s', 'issue '),
-    'pull': ('https://github.com/saltstack/salt/pull/%s', 'PR '),
+    'issue': ('https://github.com/saltstack/salt/issues/%s', 'issue #'),
+    'pull': ('https://github.com/saltstack/salt/pull/%s', 'PR #'),
     'formula_url': ('https://github.com/saltstack-formulas/%s', ''),
 }
 

doc/contents.rst

@@ -7,6 +7,7 @@ Salt Table of Contents
 .. toctree::
     :maxdepth: 2
 
+    topics/index
     topics/installation/index
     topics/configuration/index
     topics/using_salt
@@ -15,11 +16,15 @@ Salt Table of Contents
     topics/utils/index
     topics/event/index
     topics/orchestrate/index
+    topics/solaris/index
     topics/ssh/index
+    topics/thorium/index
     topics/cloud/index
     topics/proxyminion/index
     topics/virt/index
     ref/cli/index
+    ref/pillar/index
+    ref/tops/index
     ref/index
     topics/api
     topics/topology/index
@@ -28,3 +33,4 @@ Salt Table of Contents
     topics/development/index
     topics/releases/index
     topics/venafi/index
+    glossary

doc/ref/beacons/all/salt.beacons.sensehat.rst

@@ -1,5 +1,5 @@
 salt.beacons.sensehat module
-=======================
+============================
 
 .. automodule:: salt.beacons.sensehat
     :members:

doc/ref/cli/index.rst

@@ -74,6 +74,12 @@ salt-syndic
 
     salt-syndic
 
+salt-unity
+==========
+.. toctree::
+
+    salt-unity
+
 salt-api
 ========
 .. toctree::

doc/ref/cli/salt.rst

@@ -46,14 +46,6 @@ Options
     Instead of waiting for the job to run on minions only print the job id of
     the started execution and complete.
 
-.. option:: --state-output=STATE_OUTPUT
-
-    .. versionadded:: 0.17
-
-    Override the configured ``state_output`` value for minion output. One of
-    ``full``, ``terse``, ``mixed``, ``changes`` or ``filter``.  Default:
-    ``full``.
-
 .. option:: --subset=SUBSET
 
     Execute the routine on a random subset of the targeted minions.  The

doc/ref/clients/index.rst

@@ -72,6 +72,7 @@ Each module type has a corresponding loader function.
 Salt's Client Interfaces
 ========================
 
+.. _client-interfaces:
 .. _local-client:
 
 LocalClient

doc/ref/configuration/logging/index.rst

@@ -74,11 +74,14 @@ The log records can be sent to a regular file, local path name, or network
 location.  Remote logging works best when configured to use rsyslogd(8) (e.g.:
 ``file:///dev/log``), with rsyslogd(8) configured for network logging.  The
 format for remote addresses is:
-``<file|udp|tcp>://<host|socketpath>:<port-if-required>/<log-facility>``. Where
-``log-facility`` is the symbolic name of a syslog facility as defined in the
-:ref:`SysLogHandler documentation
-<python2:logging.handlers.SysLogHandler.encodePriority>` . It defaults to
-``LOG_USER``.
+
+.. code-block:: text
+
+    <file|udp|tcp>://<host|socketpath>:<port-if-required>/<log-facility>
+
+Where ``log-facility`` is the symbolic name of a syslog facility as defined in
+the :py:obj:`SysLogHandler documentation
+<logging.handlers.SysLogHandler.encodePriority>`. It defaults to ``LOG_USER``.
 
 Default: Dependent of the binary being executed, for example, for
 ``salt-master``, ``/var/log/salt/master``.
@@ -148,7 +151,7 @@ The level of messages to send to the log file. One of ``all``, ``garbage``,
 Default: ``%H:%M:%S``
 
 The date and time format used in console log messages. Allowed date/time
-formatting can be seen on :func:`time.strftime <python2:time.strftime>`.
+formatting matches those used in :py:func:`time.strftime`.
 
 .. code-block:: yaml
 
@@ -162,7 +165,7 @@ formatting can be seen on :func:`time.strftime <python2:time.strftime>`.
 Default: ``%Y-%m-%d %H:%M:%S``
 
 The date and time format used in log file messages. Allowed date/time
-formatting can be seen on :func:`time.strftime <python2:time.strftime>`.
+formatting matches those used in :py:func:`time.strftime`.
 
 .. code-block:: yaml
 
@@ -176,8 +179,8 @@ formatting can be seen on :func:`time.strftime <python2:time.strftime>`.
 Default: ``[%(levelname)-8s] %(message)s``
 
 The format of the console logging messages. All standard python logging
-:ref:`LogRecord attributes <python2:logrecord-attributes>` can be used.  Salt
-also provides these custom LogRecord attributes to colorize console log output:
+:py:class:`~logging.LogRecord` attributes can be used. Salt also provides these
+custom LogRecord attributes to colorize console log output:
 
 .. code-block:: python
 
@@ -204,9 +207,9 @@ also provides these custom LogRecord attributes to colorize console log output:
 Default: ``%(asctime)s,%(msecs)03d [%(name)-17s][%(levelname)-8s] %(message)s``
 
 The format of the log file logging messages. All standard python logging
-:ref:`LogRecord attributes <python2:logrecord-attributes>` can be used.  Salt
-also provides these custom LogRecord attributes that include padding and
-enclosing brackets ``[`` and ``]``:
+:py:class:`~logging.LogRecord` attributes can be used.  Salt also provides
+these custom LogRecord attributes that include padding and enclosing brackets
+``[`` and ``]``:
 
 .. code-block:: python
 

doc/ref/configuration/master.rst

@@ -696,31 +696,6 @@ master event bus. The value is expressed in bytes.
 
     max_event_size: 1048576
 
-.. conf_master:: ping_on_rotate
-
-``ping_on_rotate``
-------------------
-
-.. versionadded:: 2014.7.0
-
-Default:  ``False``
-
-By default, the master AES key rotates every 24 hours. The next command
-following a key rotation will trigger a key refresh from the minion which may
-result in minions which do not respond to the first command after a key refresh.
-
-To tell the master to ping all minions immediately after an AES key refresh, set
-ping_on_rotate to ``True``. This should mitigate the issue where a minion does not
-appear to initially respond after a key is rotated.
-
-Note that ping_on_rotate may cause high load on the master immediately after
-the key rotation event as minions reconnect. Consider this carefully if this
-salt master is managing a large number of minions.
-
-.. code-black:: yaml
-
-    ping_on_rotate: False
-
 .. conf_master:: master_job_cache
 
 ``master_job_cache``
@@ -840,8 +815,7 @@ Changes the underlying transport layer. ZeroMQ is the recommended transport
 while additional transport layers are under development. Supported values are
 ``zeromq``, ``raet`` (experimental), and ``tcp`` (experimental). This setting has
 a significant impact on performance and should not be changed unless you know
-what you are doing! Transports are explained in :ref:`Salt Transports
-<transports>`.
+what you are doing!
 
 .. code-block:: yaml
 
@@ -854,10 +828,10 @@ what you are doing! Transports are explained in :ref:`Salt Transports
 
 Default: ``{}``
 
-(experimental) Starts multiple transports and overrides options for each transport with the provided dictionary
-This setting has a significant impact on performance and should not be changed unless you know
-what you are doing! Transports are explained in :ref:`Salt Transports
-<transports>`. The following example shows how to start a TCP transport alongside a ZMQ transport.
+(experimental) Starts multiple transports and overrides options for each
+transport with the provided dictionary This setting has a significant impact on
+performance and should not be changed unless you know what you are doing!  The
+following example shows how to start a TCP transport alongside a ZMQ transport.
 
 .. code-block:: yaml
 
@@ -903,7 +877,7 @@ is set to ``tcp`` by default on Windows.
 
     ipc_mode: ipc
 
-.. conf_master::
+.. conf_master:: tcp_master_pub_port
 
 ``tcp_master_pub_port``
 -----------------------
@@ -976,7 +950,7 @@ a minion performs an authentication check with the master.
 .. conf_master:: minion_data_cache_events
 
 ``minion_data_cache_events``
---------------------
+----------------------------
 
 .. versionadded:: 2017.7.3
 
@@ -994,6 +968,23 @@ cache events are fired when a minion requests a minion data cache refresh.
 Salt-SSH Configuration
 ======================
 
+.. conf_master:: roster_defaults
+
+``roster_defaults``
+-------------------
+
+.. versionadded:: 2017.7.0
+
+Default settings which will be inherited by all rosters.
+
+.. code-block:: yaml
+
+    roster_defaults:
+      user: daniel
+      sudo: True
+      priv: /root/.ssh/id_rsa
+      tty: True
+
 .. conf_master:: roster_file
 
 ``roster_file``
@@ -1587,10 +1578,10 @@ constant names without ssl module prefix: ``CERT_REQUIRED`` or ``PROTOCOL_SSLv23
         certfile: <path_to_certfile>
         ssl_version: PROTOCOL_TLSv1_2
 
-.. conf_master:: allow_minion_key_revoke
+.. conf_master:: preserve_minion_cache
 
-``allow_minion_key_revoke``
----------------------------
+``preserve_minion_cache``
+-------------------------
 
 Default: ``False``
 
@@ -1619,7 +1610,7 @@ the master will drop the request and the minion's key will remain accepted.
 
 .. code-block:: yaml
 
-    rotate_aes_key: True
+    allow_minion_key_revoke: False
 
 
 Master Large Scale Tuning Settings
@@ -3868,7 +3859,7 @@ Default: ``['+refs/heads/*:refs/remotes/origin/*', '+refs/tags/*:refs/tags/*']``
 When fetching from remote repositories, by default Salt will fetch branches and
 tags. This parameter can be used to override the default and specify
 alternate refspecs to be fetched. This parameter works similarly to its
-:ref:`GitFS counterpart <git_pillar-custom-refspecs>`, in that it can be
+:ref:`GitFS counterpart <gitfs-custom-refspecs>`, in that it can be
 configured both globally and for individual remotes.
 
 .. code-block:: yaml
@@ -3916,12 +3907,14 @@ The pillar_source_merging_strategy option allows you to configure merging
 strategy between different sources. It accepts 5 values:
 
 * ``none``:
-.. versionadded:: 2016.3.4
+
   It will not do any merging at all and only parse the pillar data from the passed environment and 'base' if no environment was specified.
 
+  .. versionadded:: 2016.3.4
+
 * ``recurse``:
 
-  it will merge recursively mapping of data. For example, theses 2 sources:
+  It will recursively merge data. For example, theses 2 sources:
 
   .. code-block:: yaml
 
@@ -4169,6 +4162,7 @@ Default: ``10``
 The number of workers for the runner/wheel in the reactor.
 
 .. code-block:: yaml
+
     reactor_worker_threads: 10
 
 .. conf_master:: reactor_worker_hwm
@@ -5017,7 +5011,7 @@ Default: ``['+refs/heads/*:refs/remotes/origin/*', '+refs/tags/*:refs/tags/*']``
 When fetching from remote repositories, by default Salt will fetch branches and
 tags. This parameter can be used to override the default and specify
 alternate refspecs to be fetched. This parameter works similarly to its
-:ref:`GitFS counterpart <winrepo-custom-refspecs>`, in that it can be
+:ref:`GitFS counterpart <gitfs-custom-refspecs>`, in that it can be
 configured both globally and for individual remotes.
 
 .. code-block:: yaml