From e0110903c7dcbb21fdc2975244e04c5a07ad13d0 Mon Sep 17 00:00:00 2001
From: Brian Coca <brian.coca+git@gmail.com>
Date: Sat, 15 Nov 2014 17:01:25 -0500
Subject: [PATCH] put start and step docs into their own topic, moved from
 playbook_intro which is meant to be kept simple

---
 docsite/rst/playbooks_special_topics.rst |  1 +
 docsite/rst/playbooks_startnstep.rst     | 38 ++++++++++++++++++++++++
 2 files changed, 39 insertions(+)
 create mode 100644 docsite/rst/playbooks_startnstep.rst

diff --git a/docsite/rst/playbooks_special_topics.rst b/docsite/rst/playbooks_special_topics.rst
index 078b27f2533..c57f5796c96 100644
--- a/docsite/rst/playbooks_special_topics.rst
+++ b/docsite/rst/playbooks_special_topics.rst
@@ -17,3 +17,4 @@ and adopt these only if they seem relevant or useful to your environment.
    playbooks_prompts
    playbooks_tags
    playbooks_vault
+   playbooks_startnstep
diff --git a/docsite/rst/playbooks_startnstep.rst b/docsite/rst/playbooks_startnstep.rst
new file mode 100644
index 00000000000..1238a710d8a
--- /dev/null
+++ b/docsite/rst/playbooks_startnstep.rst
@@ -0,0 +1,38 @@
+Start and Step
+======================
+.. versionadded:: 1.8
+
+.. contents:: Topics
+
+This shows a few special ways to run playbooks, very useful for testing and debugging.
+
+
+Start-at-task
+`````````````
+.. versionadded:: 1.2
+
+If you want to start executing your playbook at a particular task, you can do so
+with the ``--start-at`` option::
+
+    ansible-playbook playbook.yml --start-at="install packages"
+
+The above will start executing your playbook at a task named "install packages".
+
+
+Step
+````
+.. versionadded:: 1.1
+
+
+Playbooks can also be executed interactively with ``--step``::
+
+    ansible-playbook playbook.yml --step
+
+This will cause ansible to stop on each task, and ask if it should execute that task.
+Say you had a task called "configure ssh", the playbook run will stop and ask::
+
+    Perform task: configure ssh (y/n/c):
+
+Answering "y" will execute the task, answering "n" will skip the task, and answering "c"
+will continue executing all the remaining tasks without asking.
+