From de60328d948929c5d5a3d892b08408288002ae8b Mon Sep 17 00:00:00 2001
From: Aidan Feldman <aidan.feldman@gmail.com>
Date: Mon, 22 Jan 2018 16:37:19 -0500
Subject: [PATCH] add documentation around commonly-used Facts for Conditionals
 (#34263)

* add documentation around commonly-used Facts for Conditionals

There are a few Facts that are often used for Conditionals, so
documenting them on the Conditionals page with their possible values.

* Edit
---
 docs/docsite/rst/playbooks_conditionals.rst   | 65 ++++++++++++++++++-
 .../module_utils/facts/system/distribution.py |  2 +
 2 files changed, 66 insertions(+), 1 deletion(-)

diff --git a/docs/docsite/rst/playbooks_conditionals.rst b/docs/docsite/rst/playbooks_conditionals.rst
index 02be8a1413d..af429183d23 100644
--- a/docs/docsite/rst/playbooks_conditionals.rst
+++ b/docs/docsite/rst/playbooks_conditionals.rst
@@ -6,7 +6,7 @@ Conditionals
 
 Often the result of a play may depend on the value of a variable, fact (something learned about the remote system), or previous task result.
 In some cases, the values of variables may depend on other variables.
-Further, additional groups can be created to manage hosts based on whether the hosts match other criteria. This topic covers how conditionals are used in playbooks. 
+Additional groups can be created to manage hosts based on whether the hosts match other criteria. This topic covers how conditionals are used in playbooks.
 
 .. note:: There are many options to control execution flow in Ansible. More examples of supported conditionals can be located here: http://jinja.pocoo.org/docs/dev/templates/#comparisons.
 
@@ -319,6 +319,69 @@ You may check the registered variable's string contents for emptiness::
             debug: msg="Directory is empty"
             when: contents.stdout == ""
 
+Commonly Used Facts
+```````````````````
+
+The following Facts (see :ref:`_vars_and_facts`) are frequently used in Conditionals - see above for examples.
+
+.. _ansible_distribution:
+
+ansible_distribution
+--------------------
+
+Possible values::
+
+    Alpine
+    Altlinux
+    Amazon
+    Archlinux
+    ClearLinux
+    Coreos
+    Debian
+    Gentoo
+    Mandriva
+    NA
+    OpenWrt
+    OracleLinux
+    RedHat
+    Slackware
+    SMGL
+    SUSE
+    VMwareESX
+
+.. See `OSDIST_LIST`
+
+.. _ansible_distribution_major_version:
+
+ansible_distribution_major_version
+----------------------------------
+
+This will be the major version of the operating system. For example, the value will be `16` for Ubuntu 16.04.
+
+.. _ansible_os_family:
+
+ansible_os_family
+-----------------
+
+Possible values::
+
+    AIX
+    Alpine
+    Altlinux
+    Archlinux
+    Darwin
+    Debian
+    FreeBSD
+    Gentoo
+    HP-UX
+    Mandrake
+    RedHat
+    SGML
+    Slackware
+    Solaris
+    Suse
+
+.. See `OS_FAMILY_MAP`
 
 .. seealso::
 
diff --git a/lib/ansible/module_utils/facts/system/distribution.py b/lib/ansible/module_utils/facts/system/distribution.py
index 992aca13c91..90dc6356e6c 100644
--- a/lib/ansible/module_utils/facts/system/distribution.py
+++ b/lib/ansible/module_utils/facts/system/distribution.py
@@ -55,6 +55,7 @@ class DistributionFiles:
     #  - allowempty == True
     #  - be listed in SEARCH_STRING
     #  - have a function get_distribution_DISTNAME implemented
+    # keep names in sync with Conditionals page of docs
     OSDIST_LIST = (
         {'path': '/etc/oracle-release', 'name': 'OracleLinux'},
         {'path': '/etc/slackware-version', 'name': 'Slackware'},
@@ -404,6 +405,7 @@ class Distribution(object):
         'SMGL': 'Source Mage GNU/Linux',
     }
 
+    # keep keys in sync with Conditionals page of docs
     OS_FAMILY_MAP = {'RedHat': ['RedHat', 'Fedora', 'CentOS', 'Scientific', 'SLC',
                                 'Ascendos', 'CloudLinux', 'PSBM', 'OracleLinux', 'OVS',
                                 'OEL', 'Amazon', 'Virtuozzo', 'XenServer'],