Merge pull request #9564 from bcoca/start_step_docs

Start step docs

3 files changed, 35 insertions, 19 deletions

diff --git a/docsite/rst/playbooks_intro.rst b/docsite/rst/playbooks_intro.rst
index cc55f28261..4bc3bccf2d 100644
--- a/docsite/rst/playbooks_intro.rst
+++ b/docsite/rst/playbooks_intro.rst
@@ -335,25 +335,6 @@ Let's run a playbook using a parallelism level of 10::
 
     ansible-playbook playbook.yml -f 10
 
-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.
-
-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".
-
 .. _ansible-pull:
 
 Ansible-Pull
diff --git a/docsite/rst/playbooks_special_topics.rst b/docsite/rst/playbooks_special_topics.rst
index 078b27f253..c57f5796c9 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 0000000000..ac06962cf2
--- /dev/null
+++ b/docsite/rst/playbooks_startnstep.rst
@@ -0,0 +1,34 @@
+Start and Step
+======================
+
+This shows a few alternative ways to run playbooks. These modes are very useful for testing new plays or debugging.
+
+
+.. _start_at_task
+
+Start-at-task
+`````````````
+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
+
+Step
+````
+
+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.
+