From 6b874d45bd6c38035bc71f0dfe0331103ee3050d Mon Sep 17 00:00:00 2001
From: Sean Myers <sean.myers@redhat.com>
Date: Sun, 17 Aug 2014 18:57:23 -0400
Subject: [PATCH] docs updates

- intrinsic conditional funcs have docstrings
- docs conf pulls version from packaging info
---
 cfn_pyplates/functions.py | 72 ++++++++++++++++++++++++++++++++++++++-
 docs/requirements.txt     |  3 ++
 docs/source/conf.py       |  9 ++---
 3 files changed, 79 insertions(+), 5 deletions(-)

diff --git a/cfn_pyplates/functions.py b/cfn_pyplates/functions.py
index 27f1d0e..f39fc35 100644
--- a/cfn_pyplates/functions.py
+++ b/cfn_pyplates/functions.py
@@ -248,14 +248,30 @@ def ref(logical_name):
         * When you specify a resource's logical name, it returns a value
             that you can typically use to refer to that resource.
 
-
     .. note:: You can also use Ref to add values to Output messages.
 
     """
     return {'Ref': logical_name}
 
 
+def c_ref(condition_name):
+    """The intrinsic function Condition used to reference a named condition
+
+    When you refer to a condition in another condition or associate the
+    condition with a resource, you use the Condition: key. For the Fn::If
+    function, you only need to specify the condition name.
+
+    Args:
+        condition_name: The name of the condition you want to reference.
+
+    Returns:
+        * A reference to the named condition
+
+    """
+
+
 def _validate_logical_condition_counts(fn, conditions):
+    # c_and / c_or have these limits applied, this keeps it DRY
     if len(conditions) < 2:
         raise IntrinsicFuncInputError(fn._errmsg_min)
     elif len(conditions) > 10:
@@ -263,6 +279,19 @@ def _validate_logical_condition_counts(fn, conditions):
 
 
 def c_and(*conditions):
+    """The intrinsic conditional function Fn::And
+
+    Returns true (for the pruposes of the cfn template) if all the specified conditions
+    evaluate to true, or returns false if any one of the conditions evaluates to false.
+
+    Fn::And acts as an AND operator.
+
+    The minimum number of conditions that you can include is 2, and the maximum is 10.
+
+    Args:
+        *conditions: The conditions to evaluate
+
+    """
     _validate_logical_condition_counts(c_and, conditions)
     return {'Fn::And': list(conditions)}
 c_and._errmsg_min = "Minimum umber of conditions for 'c_and' condition is 2"
@@ -270,6 +299,19 @@ def c_and(*conditions):
 
 
 def c_or(*conditions):
+    """The intrinsic conditional function Fn::Or
+
+    Returns true (for the pruposes of the cfn template) if any one of the specified conditions
+    evaluate to true, or returns false if all of the conditions evaluates to false.
+
+    Fn::Or acts as an OR operator.
+
+    The minimum number of conditions that you can include is 2, and the maximum is 10.
+
+    Args:
+        *conditions: The conditions to evaluate
+
+    """
     _validate_logical_condition_counts(c_or, conditions)
     return {'Fn::Or': list(conditions)}
 c_or._errmsg_min = "Minimum umber of conditions for 'c_or' condition is 2"
@@ -277,12 +319,40 @@ def c_or(*conditions):
 
 
 def c_not(condition):
+    """The intrinsic conditional function Fn::Not
+
+    Returns true for a condition that evaluates to false or
+    returns false for a condition that evaluates to true.
+
+    Fn::Not acts as a NOT operator.
+
+    """
     return {'Fn::Not': [condition]}
 
 
 def c_equals(value_1, value_2):
+    """The intrinsic conditional function Fn::Equals
+
+    Compares if two values are equal.
+
+    Returns true if the two values are equal or false if they aren't.
+
+    """
     return {'Fn::Equals': [value_1, value_2]}
 
 
 def c_if(condition_name, value_if_true, value_if_false):
+    """The intrinsic conditional function Fn::If representsa a ternary conditional operator
+
+    Returns one value if the specified condition evaluates to true and another value
+    if the specified condition evaluates to false.
+
+    Currently, AWS CloudFormation supports the Fn::If intrinsic function in the
+    metadata attribute, update policy attribute, and property values in the Resources
+    section and Outputs sections of a template.
+
+    You can use the AWS::NoValue pseudo parameter as a return value
+    to remove the corresponding property.
+
+    """
     return {'Fn::If': [condition_name, value_if_true, value_if_false]}
diff --git a/docs/requirements.txt b/docs/requirements.txt
index 333759d..67bea11 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -5,3 +5,6 @@ Sphinx
 
 # this lets you write docstrings according to the google python style guide
 cartouche
+
+# docs need pbr to help with versions
+pbr
diff --git a/docs/source/conf.py b/docs/source/conf.py
index f14b0a5..b1e0a54 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -11,8 +11,9 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import cfn_pyplates
-import sys, os
+from pkg_resources import require
+
+version = require("cfn-pyplates")[0].version
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -54,9 +55,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = cfn_pyplates.__version__
+version = '.'.join(version.split('.', 2)[:2])
 # The full version, including alpha/beta/rc tags.
-release = cfn_pyplates.__version__
+release = version
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.