Fix incremental doc builds - OS X, postgres returner, tcp transport doc updates (#35865)

* Updates doc builds to generate build timestamp only when building for docs.saltstack.com. This re-enables incremental builds.
Adds notes to OS X page that Salt master on OS X is not officially supported
Adds note to postgres returners to cross-link modules with usage explanation (ZD #875)
Adds example showing how to enable tcp transport

* Generate copyright date
Footer updates

doc/_themes/saltstack2/layout.html

@@ -225,7 +225,7 @@
 
                             {% if on_saltstack %}
                             <div class="col-sm-6">
-                            <p><i>Generated on {{today}}.</i></p>
+                            <p><i>{{ today }}</i></p>
 
                                 {% if build_type == "latest" %}
                                 <p>You are viewing docs for the latest stable release, {{ latest_release }}. Switch to docs for the previous stable release, <a data-container="body" data-toggle="tooltip" data-placement="bottom" title="Docs for the previous stable release" href="/en/{{ previous_release_dir }}/">{{ previous_release }}</a>, or to a recent doc build from the <a data-container="body" data-toggle="tooltip" data-placement="bottom" title="Latest docs from the develop branch" href="/en/develop/">develop</a> branch.</p>
@@ -245,6 +245,9 @@
                                 <br>
                                 <p><a href="http://saltstack.com">saltstack.com</a></p>
 
+                                <div class="footer">
+                                    <p>© {{ copyright }} SaltStack. All Rights Reserved, SaltStack Inc. | <a href="http://saltstack.com/privacy-policy" target="_blank">Privacy Policy</a></p>
+                                </div>
                             </div>
 
                             <div class="col-sm-6">

doc/_themes/saltstack2/static/css/webhelp.min_v1.4.5.css

@@ -416,6 +416,7 @@ div.admonition p.admonition-title{font-weight:700;color:#3465a4}
 div.warning{border-color:#940000}
 div.warning p.admonition-title{color:#940000}
 div.viewcode-block:target{background-color:#f4debf;border-top:1px solid #ac9;border-bottom:1px solid #ac9}
+.footer p{text-align:left;color:#777;font-size:13px;margin:0}
 .lit-docs{list-style-type:none;margin:0}
 .lit-item{padding-bottom:2em}
 .lit-annotation,.lit-content{display:inline-block;vertical-align:top}

doc/conf.py

@@ -207,8 +207,10 @@ intersphinx_mapping = {
 
 # -- General Configuration -----------------------------------------------------
 
+# Set a var if we're building docs for the live site or not
+on_saltstack = 'SALT_ON_SALTSTACK' in os.environ
+
 project = 'Salt'
-copyright = '2016 SaltStack, Inc.'
 
 version = salt.version.__version__
 latest_release = '2016.3.2'  # latest release
@@ -217,7 +219,11 @@ previous_release_dir = '2015.8'  # path on web server for previous branch
 next_release = ''  # next release
 next_release_dir = ''  # path on web server for next release branch
 
-today = time.strftime("%B %d, %Y") + " at " + time.strftime("%X %Z")
+today = ''
+copyright = ''
+if on_saltstack:
+    today = "Generated on " + time.strftime("%B %d, %Y") + " at " + time.strftime("%X %Z") + "."
+    copyright = time.strftime("%Y")
 
 # < --- START do not merge these settings to other branches START ---> #
 build_type = 'latest'  # latest, previous, develop, next
@@ -321,9 +327,6 @@ html_logo = None # specified in the theme layout.html
 html_favicon = 'favicon.ico'
 html_use_smartypants = False
 
-# Set a var if we're building docs for the live site or not
-on_saltstack = 'SALT_ON_SALTSTACK' in os.environ
-
 # Use Google customized search or use Sphinx built-in JavaScript search
 if on_saltstack:
     html_search_template = 'googlesearch.html'
@@ -370,6 +373,7 @@ html_context = {
     'search_cx': search_cx,
     'build_type': build_type,
     'today': today,
+    'copyright': copyright,
 }
 
 html_use_index = True

doc/topics/installation/osx.rst

@@ -45,6 +45,9 @@ When only using the OS X system's pip, install this way:
 
 Salt-Master Customizations
 ==========================
+.. note::
+    Salt master on OS X is not tested or supported by SaltStack. See `SaltStack Platform Support <https://saltstack.com/product-support-lifecycle/>`_ for more information.
+
 To run salt-master on OS X, sudo add this configuration option to the /etc/salt/master file:
 
 .. code-block:: bash

doc/topics/transports/tcp.rst

@@ -2,10 +2,16 @@
 TCP Transport
 =============
 
-The "tcp" transport is an implementation of Salt's channels using raw tcp sockets.
+The tcp transport is an implementation of Salt's channels using raw tcp sockets.
 Since this isn't using a pre-defined messaging library we will describe the wire
 protocol, message semantics, etc. in this document.
 
+The tcp transport is enabled by changing the :conf_minion:`transport` setting
+to ``tcp`` on each Salt minion and Salt master.
+
+.. code-block:: yaml
+
+   transport: tcp
 
 Wire Protocol
 =============

salt/returners/postgres.py

@@ -2,6 +2,13 @@
 '''
 Return data to a postgresql server
 
+.. note::
+    :mod:`returners.postgres_local_cache <salt.returners.postgres_local_cache>`
+    is recommended instead of this module when using PostgreSQL as a
+    :ref:`master job cache <external-master-cache>`. These two modules
+    provide different functionality so you should compare each to see which
+    module best suits your particular needs.
+
 :maintainer:    None
 :maturity:      New
 :depends:       psycopg2

salt/returners/postgres_local_cache.py

@@ -3,6 +3,13 @@
 Use a postgresql server for the master job cache. This helps the job cache to
 cope with scale.
 
+.. note::
+    :mod:`returners.postgres <salt.returners.postgres>` is also available if
+    you are not using PostgreSQL as a :ref:`master job cache
+    <external-master-cache>`.  These two modules provide different
+    functionality so you should compare each to see which module best suits
+    your particular needs.
+
 :maintainer:    gjredelinghuys@gmail.com
 :maturity:      New
 :depends:       psycopg2