removed link to guide, and added more documentation and examples

web_infrastructure/deploy_helper.py

@@ -5,12 +5,21 @@ DOCUMENTATION = '''
 module: deploy_helper
 version_added: "1.8"
 author: Ramon de la Fuente, Jasper N. Brouwer
-short_description: Manages the folders for deploy of a project
+short_description: Manages some of the steps common in deploying projects.
 description:
-  - Manages some of the steps common in deploying projects.
+  - The Deploy Helper manages some of the steps common in deploying software.
-    It creates a folder structure, cleans up old releases and manages a symlink for the current release.
+    It creates a folder structure, manages a symlink for the current release
-
+    and cleans up old releases.
-    For more information, see the :doc:`guide_deploy_helper`
+  - "Running it with the C(state=query) or C(state=present) will return the C(deploy_helper) fact.
+    C(project_path), whatever you set in the path parameter,
+    C(current_path), the path to the symlink that points to the active release,
+    C(releases_path), the path to the folder to keep releases in,
+    C(shared_path), the path to the folder to keep shared resources in,
+    C(unfinished_filename), the file to check for to recognize unfinished builds,
+    C(previous_release), the release the 'current' symlink is pointing to,
+    C(previous_release_path), the full path to the 'current' symlink target,
+    C(new_release), either the 'release' parameter or a generated timestamp,
+    C(new_release_path), the path to the new release folder (not created by the module)."
 
 options:
   path:
@@ -18,6 +27,7 @@ options:
     aliases: ['dest']
     description:
       - the root path of the project. Alias I(dest).
+        Returned in the C(deploy_helper.project_path) fact.
 
   state:
     required: false
@@ -26,23 +36,25 @@ options:
     description:
       - the state of the project.
         C(query) will only gather facts,
-        C(present) will create the project,
+        C(present) will create the project I(root) folder, and in it the I(releases) and I(shared) folders,
-        C(finalize) will create a symlink to the newly deployed release,
+        C(finalize) will remove the unfinished_filename file, create a symlink to the newly
+          deployed release and optionally clean old releases,
         C(clean) will remove failed & old releases,
-        C(absent) will remove the project folder (synonymous to M(file) with state=absent)
+        C(absent) will remove the project folder (synonymous to the M(file) module with C(state=absent))
 
   release:
     required: false
     description:
-      - the release version that is being deployed (defaults to a timestamp %Y%m%d%H%M%S). This parameter is
+      - the release version that is being deployed. Defaults to a timestamp format %Y%m%d%H%M%S (i.e. '20141119223359').
-        optional during C(state=present), but needs to be set explicitly for C(state=finalize). You can use the
+        This parameter is optional during C(state=present), but needs to be set explicitly for C(state=finalize).
-        generated fact C(release={{ deploy_helper.new_release }})
+        You can use the generated fact C(release={{ deploy_helper.new_release }}).
 
   releases_path:
     required: false
     default: releases
     description:
       - the name of the folder that will hold the releases. This can be relative to C(path) or absolute.
+        Returned in the C(deploy_helper.releases_path) fact.
 
   shared_path:
     required: false
@@ -50,12 +62,14 @@ options:
     description:
       - the name of the folder that will hold the shared resources. This can be relative to C(path) or absolute.
         If this is set to an empty string, no shared folder will be created.
+        Returned in the C(deploy_helper.shared_path) fact.
 
   current_path:
     required: false
     default: current
     description:
       - the name of the symlink that is created when the deploy is finalized. Used in C(finalize) and C(clean).
+        Returned in the C(deploy_helper.current_path) fact.
 
   unfinished_filename:
     required: false
@@ -81,7 +95,7 @@ options:
 notes:
   - Facts are only returned for C(state=query) and C(state=present). If you use both, you should pass any overridden
     parameters to both calls, otherwise the second call will overwrite the facts of the first one.
-  - When using C(state=clean), the releases are ordered by creation date. You should be able to switch to a
+  - When using C(state=clean), the releases are ordered by I(creation date). You should be able to switch to a
     new naming strategy without problems.
   - Because of the default behaviour of generating the I(new_release) fact, this module will not be idempotent
     unless you pass your own release name with C(release). Due to the nature of deploying software, this should not
@@ -89,41 +103,50 @@ notes:
 '''
 
 EXAMPLES = '''
-Example usage for the deploy_helper module.
+
-
+# Typical usage:
-  tasks:
+- name: Initialize the deploy root and gather facts
-    # Typical usage:
+  deploy_helper: path=/path/to/root
-    - deploy_helper: path=/path/to/root state=present
+- name: Clone the project to the new release folder
-    ...some_build_steps_here, like a git clone to {{ deploy_helper.new_release_path }} for example...
+  git: repo=git://foosball.example.org/path/to/repo.git dest={{ deploy.new_release_path }} version=v1.1.1"
-    - deploy_helper: path=/path/to/root release={{ deploy_helper.new_release }} state=finalize
+- name: Add an unfinished file, to allow cleanup on successful finalize
-
+  file: path={{ deploy.new_release_path }}/{{ deploy.unfinished_filename }} state=touch
-    # Gather information only
+- name: Perform some build steps, like running your dependency manager for example
-    - deploy_helper: path=/path/to/root state=query
+  composer: command=install working_dir={{ deploy.new_release_path }}
-    # Remember to set the 'release=' when you actually call state=present later
+- name: Finalize the deploy, removing the unfinished file and switching the symlink
-    - deploy_helper: path=/path/to/root release={{ deploy_helper.new_release }} state=present
+  deploy_helper: path=/path/to/root release={{ deploy_helper.new_release }} state=finalize
-
+
-    # all paths can be absolute or relative (to 'path')
+# Retrieving facts before running a deploy
-    - deploy_helper: path=/path/to/root
+- name: Run query to gather facts without changing anything
-                     releases_path=/var/www/project/releases
+  deploy_helper: path=/path/to/root state=query
-                     shared_path=/var/www/shared
+  # Remember to set the 'release' parameter when you actually call state=present
-                     current_path=/var/www/active
+- name: Initialize the deploy root
-
+  deploy_helper: path=/path/to/root release={{ deploy_helper.new_release }} state=present
-    # Using your own naming strategy:
+
-    - deploy_helper: path=/path/to/root release=v1.1.1 state=present
+# all paths can be absolute or relative (to the 'path' parameter)
-    - deploy_helper: path=/path/to/root release={{ deploy_helper.new_release }} state=finalize
+- deploy_helper: path=/path/to/root
-
+                 releases_path=/var/www/project/releases
-    # Postponing the cleanup of older builds:
+                 shared_path=/var/www/shared
-    - deploy_helper: path=/path/to/root release={{ deploy_helper.new_release }} state=finalize clean=False
+                 current_path=/var/www/active
-    ...anything you do before actually deleting older releases...
+
-    - deploy_helper: path=/path/to/root state=clean
+# Using your own naming strategy:
-
+- deploy_helper: path=/path/to/root release=v1.1.1 state=present
-    # Keeping more old releases:
+- deploy_helper: path=/path/to/root release={{ deploy_helper.new_release }} state=finalize
-    - deploy_helper: path=/path/to/root release={{ deploy_helper.new_release }} state=finalize keep_releases=10
+
-    # Or:
+# Using a different unfinished_filename:
-    - deploy_helper: path=/path/to/root state=clean keep_releases=10
+- deploy_helper: path=/path/to/root
-
+                 unfinished_filename=README.md
-    # Using a different unfinished_filename:
+                 release={{ deploy_helper.new_release }}
-    - deploy_helper: path=/path/to/root unfinished_filename=README.md release={{ deploy_helper.new_release }} state=finalize
+                 state=finalize
+
+# Postponing the cleanup of older builds:
+- deploy_helper: path=/path/to/root release={{ deploy_helper.new_release }} state=finalize clean=False
+- deploy_helper: path=/path/to/root state=clean
+
+# Keeping more old releases:
+- deploy_helper: path=/path/to/root release={{ deploy_helper.new_release }} state=finalize keep_releases=10
+# Or:
+- deploy_helper: path=/path/to/root state=clean keep_releases=10
 
 '''