Autointerpreter table (#60148)

* Some framework for docs

* Separate CSS file for our site-specific CSS.
* Override the read-the-docs theme for tables so that tables don't
  always horizontally scroll
* Add a |br| substitution that lets us line break inside of tables
* Add |_| non-breaking-space substitution which is also for formatting
  tables
* Configure rstcheck to ignore all substitutions which are being added
  by sphinx in the conf.py

* Fix table of auto interpreter options

The table was being hardcoded at a certain width to work around a
read-the-docs theme bug.  Fix the bug instead and format the table using
better sphinx practices.

* Remove unused substitutions

We had substitutions defined that were never used in our documentation.
Remove those.

Also add to the rstcheck whitelist three substitutions which are defined
by sphinx itself, version, release, and today.

docs/docsite/_static/ansible.css

@@ -0,0 +1,16 @@
+/* Fix for read the docs theme:
+ * https://rackerlabs.github.io/docs-rackspace/tools/rtd-tables.html
+ */
+/* override table width restrictions */
+@media screen and (min-width: 767px) {
+
+   .wy-table-responsive table td {
+      /* !important prevents the common CSS stylesheets from overriding
+         this as on RTD they are loaded after this stylesheet */
+      white-space: normal !important;
+   }
+
+   .wy-table-responsive {
+      overflow: visible !important;
+   }
+}

docs/docsite/rst/conf.py

@@ -112,17 +112,14 @@ highlight_language = 'YAML+Jinja'
 
 # Substitutions, variables, entities, & shortcuts for text which do not need to link to anything.
 # For titles which should be a link, use the intersphinx anchors set at the index, chapter, and section levels, such as  qi_start_:
+# |br| is useful for formatting fields inside of tables
+# |_| is a nonbreaking space; similarly useful inside of tables
 rst_epilog = """
-.. |acapi| replace:: *Ansible Core API Guide*
-.. |acrn| replace:: *Ansible Core Release Notes*
-.. |ac| replace:: Ansible Core
-.. |acversion| replace:: Ansible Core Version 2.1
-.. |acversionshort| replace:: Ansible Core 2.1
-.. |versionshortest| replace:: 2.2
-.. |versiondev| replace:: 2.3
-.. |pubdate| replace:: July 19, 2016
-.. |rhel| replace:: Red Hat Enterprise Linux
+.. |br| raw:: html
 
+   <br>
+.. |_| unicode:: 0xA0
+    :trim:
 """
 
 
@@ -148,7 +145,9 @@ html_context = {
     'current_version': version,
     'latest_version': '2.8',
     # list specifically out of order to make latest work
-    'available_versions': ('latest', '2.7', '2.6', 'devel')
+    'available_versions': ('latest', '2.7', '2.6', 'devel'),
+    'css_files': ('_static/ansible.css',  # overrides to the standard theme
+                  ),
 }
 
 # The style sheet to use for HTML and HTML Help pages. A file of that name

docs/docsite/rst/porting_guides/porting_guide_2.8.rst

@@ -100,32 +100,32 @@ If you prefer to use the Python interpreter discovery behavior, use
 one of the four new values for ``ansible_python_interpreter`` introduced in
 Ansible 2.8:
 
-+---------------------------+-----------------------------------------------+
-| New value                 | Behavior                                      |
-+===========================+===============================================+
-| | auto                    | | If a Python interpreter is discovered,      |
-| | (future default)        | | Ansible uses the discovered Python, even if |
-| |                         | | :command:`/usr/bin/python` is also present. |
-| |                         | | Warns when using the fallback list.         |
-+---------------------------+-----------------------------------------------+
-| | **auto_legacy**         | | If a Python interpreter is discovered, and  |
-| | (Ansible 2.8 default)   | | :command:`/usr/bin/python` is absent,       |
-| |                         | | Ansible uses the discovered Python. Warns   |
-| |                         | | when using the fallback list.               |
-| |                         | |                                             |
-| |                         | | If a Python interpreter is discovered, and  |
-| |                         | | :command:`/usr/bin/python` is present,      |
-| |                         | | Ansible uses :command:`/usr/bin/python` and |
-| |                         | | prints a deprecation warning about future   |
-| |                         | | default behavior. Warns when using the      |
-| |                         | | fallback list.                              |
-+---------------------------+-----------------------------------------------+
-| | auto_legacy_silent      | | Behaves like ``auto_legacy`` but suppresses |
-| |                         | | the deprecation and fallback-list warnings. |
-+---------------------------+-----------------------------------------------+
-| | auto_silent             | | Behaves like ``auto`` but suppresses the    |
-| |                         | | fallback-list warning.                      |
-+---------------------------+-----------------------------------------------+
++---------------------------+---------------------------------------------+
+| New value                 | Behavior                                    |
++===========================+=============================================+
+| auto |br|                 | If a Python interpreter is discovered,      |
+| (future default)          | Ansible uses the discovered Python, even if |
+|                           | :command:`/usr/bin/python` is also present. |
+|                           | Warns when using the fallback list.         |
++---------------------------+---------------------------------------------+
+| **auto_legacy** |br|      | If a Python interpreter is discovered, and  |
+| (Ansible 2.8 default)     | :command:`/usr/bin/python` is absent,       |
+|                           | Ansible uses the discovered Python. Warns   |
+|                           | when using the fallback list.               |
+|                           |                                             |
+|                           | If a Python interpreter is discovered, and  |
+|                           | :command:`/usr/bin/python` is present,      |
+|                           | Ansible uses :command:`/usr/bin/python` and |
+|                           | prints a deprecation warning about future   |
+|                           | default behavior. Warns when using the      |
+|                           | fallback list.                              |
++---------------------------+---------------------------------------------+
+| auto_legacy_silent        | Behaves like ``auto_legacy`` but suppresses |
+|                           | the deprecation and fallback-list warnings. |
++---------------------------+---------------------------------------------+
+| auto_silent               | Behaves like ``auto`` but suppresses the    |
+|                           | fallback-list warning.                      |
++---------------------------+---------------------------------------------+
 
 
 In Ansible 2.12, Ansible will switch the default from :literal:`auto_legacy` to :literal:`auto`.

test/lib/ansible_test/_data/sanity/rstcheck/ignore-substitutions.txt

@@ -1,2 +1,5 @@
 version
-versiondev
+release
+today
+br
+_