From eeb80c695f2d4ab25bb8f2353370cdd2eb0f157c Mon Sep 17 00:00:00 2001
From: Jan-Piet Mens <jpmens@gmail.com>
Date: Sat, 11 May 2013 16:31:47 +0200
Subject: [PATCH] Add Requirements to rst template, ansible-doc tweak position
 & look of Requirements in rst tweak APT's notes as per anhj's wish

---
 bin/ansible-doc          |  6 ++++++
 hacking/templates/rst.j2 | 13 +++++++++++++
 library/packaging/apt    |  6 ++++--
 3 files changed, 23 insertions(+), 2 deletions(-)

diff --git a/bin/ansible-doc b/bin/ansible-doc
index 5c7d8742bec..5392ecdd51b 100755
--- a/bin/ansible-doc
+++ b/bin/ansible-doc
@@ -86,6 +86,11 @@ def print_man(doc):
                             subsequent_indent=opt_indent)
 
 
+    if 'requirements' in doc and len(doc['requirements']) > 0:
+        req = ", ".join(doc['requirements'])
+        print "Requirements:%s\n" % textwrap.fill(tty_ify(req), initial_indent="  ",
+                            subsequent_indent=opt_indent)
+
     if 'examples' in doc and len(doc['examples']) > 0:
         print "Example%s:\n" % ('' if len(doc['examples']) < 2 else 's')
         for ex in doc['examples']:
@@ -94,6 +99,7 @@ def print_man(doc):
     if 'plainexamples' in doc and doc['plainexamples'] is not None:
         print doc['plainexamples']
 
+
 def print_snippet(doc):
 
     desc = tty_ify("".join(doc['short_description']))
diff --git a/hacking/templates/rst.j2 b/hacking/templates/rst.j2
index 7e32090641b..6ac18e3b149 100644
--- a/hacking/templates/rst.j2
+++ b/hacking/templates/rst.j2
@@ -42,6 +42,18 @@
     </table>
 {% endif %}
 
+{% if requirements %}
+.. raw:: html
+
+    <p>
+    <b>Requirements:</b> 
+    {% for req in requirements %}
+    @{ req | html_ify }@
+    {% endfor %}
+    </p>
+
+{% endif %}
+
 .. raw:: html
 
 {% for example in examples %}
@@ -62,6 +74,7 @@
     </pre>
 {% endif %}
 
+
 {% if notes %}
 .. raw:: html
 
diff --git a/library/packaging/apt b/library/packaging/apt
index 50049196e38..41380e63ccf 100644
--- a/library/packaging/apt
+++ b/library/packaging/apt
@@ -82,8 +82,11 @@ options:
     required: false
     default: "yes"
     choices: [ "yes", "safe", "full", "dist"]
+requirements: [ python-apt, aptitude ]
 author: Matthew Williams
-notes: []
+notes:
+   - Two of the upgrade modes (C(full) and C(dist)) require C(aptitude), otherwise
+     C(apt-get) suffices.
 examples:
     - code: "apt: pkg=foo update_cache=yes"
       description: Update repositories cache and install C(foo) package
@@ -103,7 +106,6 @@ examples:
       description: Run the equivalent of C(apt-get update) as a separate step
     - code: "apt: update_cache=yes cache_valid_time=3600"
       description: Only run C(update_cache=yes) if the last one is more than more than 3600 seconds ago
-requirements: [ python-apt, aptitude ]
 '''
 
 import traceback