User guide overhaul, Table of Contents (#71553)

docs/docsite/rst/user_guide/index.rst

@@ -1,10 +1,85 @@
+.. _user_guide_index:
+
 ##########
 User Guide
 ##########
 
-Welcome to the Ansible User Guide!
+Welcome to the Ansible User Guide! This guide covers how to work with Ansible, including using the command line, working with inventory, interacting with data, writing tasks, plays, and playbooks; executing playbooks, and reference materials. This page outlines the most common situations and questions that bring readers to this section. If you prefer a traditional table of contents, you can find one at the bottom of the page.
+
+Getting started
+===============
+
+* I'd like an overview of how Ansible works. Where can I find:
+
+  * a :ref:`quick video overview <quickstart_guide>`
+  * a :ref:`text introduction <intro_getting_started>`
+
+* I'm ready to learn about Ansible. What :ref:`basic_concepts` do I need to learn?
+* I want to use Ansible without writing a playbook. How do I use :ref:`ad-hoc commands <intro_adhoc>`?
+
+Writing tasks, plays, and playbooks
+===================================
+
+* I'm writing my first playbook. What should I :ref:`know before I begin <playbooks_tips_and_tricks>`?
+* I have a specific use case for a task or play:
+
+  * Executing tasks with elevated privileges or as a different user with :ref:`become <become>`
+  * Repeating a task once for each item in a list with :ref:`loops <playbooks_loops>`
+  * Executing tasks on a different machine with :ref:`delegation <playbooks_delegation>`
+  * Running tasks only when certain conditions apply with :ref:`conditionals <playbooks_conditionals>` and evaluating conditions with :ref:`tests <playbooks_tests>`
+  * Grouping a set of tasks together with :ref:`blocks <playbooks_blocks>`
+  * Running tasks only when something has changed with :ref:`handlers <handlers>`
+  * Changing the way Ansible :ref:`handles failures <playbooks_error_handling>`)
+  * Setting remote :ref:`environment values <playbooks_environment>`
+
+* I want to leverage the power of re-usable Ansible artifacts. How do I create re-usable :ref:`files <playbooks_reuse>` and :ref:`roles <playbooks_reuse_roles>`?
+* I need to incorporate one file or playbook inside another. What is the difference between :ref:`including and importing <playbooks_reuse_includes>`?
+* I want to run selected parts of my playbook. How do I add and use :ref:`tags <tags>`?
+
+Working with inventory
+======================
+
+* I have a list of servers and devices I want to automate. How do I create :ref:`inventory <intro_inventory>` to track them?
+* I use cloud services and constantly have servers and devices starting and stopping. How do I track them using :ref:`dynamic inventory <intro_dynamic_inventory>`?
+* I want to automate specific sub-sets of my inventory. How do I use :ref:`patterns <intro_patterns>`?
+
+Interacting with data
+=====================
+
+* I want to use a single playbook against multiple systems with different attributes. How do I use :ref:`variables <playbooks_variables>` to handle the differences?
+* I want to retrieve data about my systems. How do I access :ref:`Ansible facts <vars_and_facts>`?
+* I need to access sensitive data like passwords with Ansible. How can I protect that data with :ref:`Ansible vault <vault>`?
+* I want to change the data I have, so I can use it in a task. How do I use :ref:`filters <playbooks_filters>` to transform my data?
+* I need to retrieve data from an external datastore. How do I use :ref:`lookups <playbooks_lookups>` to access databases and APIs?
+* I want to ask playbook users to supply data. How do I get user input with :ref:`prompts <playbooks_prompts>`?
+* I use certain modules frequently. How do I streamline my inventory and playbooks by :ref:`setting default values for module parameters <module_defaults>`?
 
-This guide covers how to work with Ansible, including using the command line, working with inventory, and writing playbooks.
+Executing playbooks
+===================
+
+Once your playbook is ready to run, you may need to use these topics:
+
+* Executing "dry run" playbooks with :ref:`check mode and diff <check_mode_dry>`
+* Running playbooks while troubleshooting with :ref:`start and step <playbooks_start_and_step>`
+* Correcting tasks during execution with the :ref:`Ansible debugger <playbook_debugger>`
+* Controlling how my playbook executes with :ref:`strategies and more <playbooks_strategies>`
+* Running tasks, plays, and playbooks :ref:`asynchronously <playbooks_async>`
+
+Advanced features and reference
+===============================
+
+* Using :ref:`advanced syntax <playbooks_advanced_syntax>`
+* Manipulating :ref:`complex data <complex_data_manipulation>`
+* Using :ref:`plugins <plugins_lookup>`
+* Using :ref:`playbook keywords <playbook_keywords>`
+* Using :ref:`command-line tools <command_line_tools>`
+* Rejecting :ref:`specific modules <plugin_filtering_config>`
+* Module :ref:`maintenance <modules_support>`
+
+Traditional Table of Contents
+=============================
+
+If you prefer to read the entire User Guide, here's a list of the pages in order:
 
 .. toctree::
    :maxdepth: 2
@@ -12,18 +87,47 @@ This guide covers how to work with Ansible, including using the command line, wo
    quickstart
    basic_concepts
    intro_getting_started
+   intro_adhoc
+   playbooks
+   playbooks_intro
+   playbooks_best_practices
+   become
+   playbooks_loops
+   playbooks_delegation
+   playbooks_conditionals
+   playbooks_tests
+   playbooks_blocks
+   playbooks_handlers
+   playbooks_error_handling
+   playbooks_environment
+   playbooks_reuse
+   playbooks_reuse_roles
+   playbooks_reuse_includes
+   playbooks_tags
    intro_inventory
    intro_dynamic_inventory
    intro_patterns
-   intro_adhoc
    connection_details
    command_line_tools
-   playbooks
-   become
+   playbooks_variables
+   playbooks_vars_facts
    vault
+   playbooks_filters
+   playbooks_lookups
+   playbooks_prompts
+   playbooks_module_defaults
+   playbooks_checkmode
+   playbooks_startnstep
+   playbooks_debugger
+   playbooks_strategies
+   playbooks_async
+   playbooks_advanced_syntax
+   complex_data_manipulation
+   plugin_filtering_config
    sample_setup
    modules
    ../plugins/plugins
+   ../reference_appendices/playbooks_keywords
    intro_bsd
    windows
    collections_using

docs/docsite/rst/user_guide/intro.rst

@@ -10,11 +10,6 @@ Before we start exploring the main components of Ansible -- playbooks, configura
 
    ../installation_guide/index
    ../dev_guide/overview_architecture
-   intro_getting_started
-   intro_inventory
-   intro_dynamic_inventory
-   intro_patterns
-   intro_adhoc
    ../installation_guide/intro_configuration
    intro_bsd
    intro_windows

docs/docsite/rst/user_guide/playbooks.rst

@@ -3,32 +3,19 @@
 Working with playbooks
 ======================
 
-Playbooks are Ansible's configuration, deployment, and orchestration language. They can describe a policy you want your remote systems to enforce, or a set of steps in a general IT process.
+Playbooks record and execute Ansible's configuration, deployment, and orchestration functions. They can describe a policy you want your remote systems to enforce, or a set of steps in a general IT process.
 
 If Ansible modules are the tools in your workshop, playbooks are your instruction manuals, and your inventory of hosts are your raw material.
 
 At a basic level, playbooks can be used to manage configurations of and deployments to remote machines.  At a more advanced level, they can sequence multi-tier rollouts involving rolling updates, and can delegate actions to other hosts, interacting with monitoring servers and load balancers along the way.
 
-While there's a lot of information here, there's no need to learn everything at once.  You can start small and pick up more features over time as you need them.
-
-Playbooks are designed to be human-readable and are developed in a basic text language.  There are multiple
-ways to organize playbooks and the files they include, and we'll offer up some suggestions on that and making the most out of Ansible.
+Playbooks are designed to be human-readable and are developed in a basic text language.  There are multiple ways to organize playbooks and the files they include, and we'll offer up some suggestions on that and making the most out of Ansible.
 
 You should look at `Example Playbooks <https://github.com/ansible/ansible-examples>`_ while reading along with the playbook documentation.  These illustrate best practices as well as how to put many of the various concepts together.
 
 .. toctree::
    :maxdepth: 2
 
-   playbooks_intro
-   playbooks_best_practices
-   playbooks_reuse
-   playbooks_reuse_roles
-   playbooks_variables
-   playbooks_vars_facts
    playbooks_templating
-   playbooks_conditionals
-   playbooks_loops
-   playbooks_blocks
    playbooks_special_topics
-   playbooks_strategies
    guide_rolling_upgrade

docs/docsite/rst/user_guide/playbooks_handlers.rst

@@ -0,0 +1,137 @@
+.. _handlers:
+
+Handlers: running operations on change
+======================================
+
+Sometimes you want a task to run only when a change is made on a machine. For example, you may want to restart a service if a task updates the configuration of that service, but not if the configuration is unchanged. Ansible uses handlers to address this use case. Handlers are tasks that only run when notified. Each handler should have a globally unique name.
+
+.. contents::
+   :local:
+
+Handler example
+---------------
+
+This playbook, ``verify-apache.yml``, contains a single play with a handler::
+
+    ---
+    - name: verify apache installation
+      hosts: webservers
+      vars:
+        http_port: 80
+        max_clients: 200
+      remote_user: root
+      tasks:
+      - name: ensure apache is at the latest version
+        yum:
+          name: httpd
+          state: latest
+      - name: write the apache config file
+        template:
+          src: /srv/httpd.j2
+          dest: /etc/httpd.conf
+        notify:
+        - restart apache
+      - name: ensure apache is running
+        service:
+          name: httpd
+          state: started
+      handlers:
+        - name: restart apache
+          service:
+            name: httpd
+            state: restarted
+
+In this example playbook, the second task notifies the handler. A single task can notify more than one handler::
+
+    - name: template configuration file
+      template:
+        src: template.j2
+        dest: /etc/foo.conf
+      notify:
+        - restart memcached
+        - restart apache
+      handlers:
+        - name: restart memcached
+          service:
+            name: memcached
+            state: restarted
+        - name: restart apache
+          service:
+            name: apache
+            state: restarted
+
+Controlling when handlers run
+-----------------------------
+
+By default, handlers run after all the tasks in a particular play have been completed. This approach is efficient, because the handler only runs once, regardless of how many tasks notify it. For example, if multiple tasks update a configuration file and notify a handler to restart Apache, Ansible only bounces Apache once to avoid unnecessary restarts.
+
+If you need handlers to run before the end of the play, add a task to flush them using the :ref:`meta module <meta_module>`, which executes Ansible actions::
+
+    tasks:
+      - shell: some tasks go here
+      - meta: flush_handlers
+      - shell: some other tasks
+
+The ``meta: flush_handlers`` task triggers any handlers that have been notified at that point in the play.
+
+Using variables with handlers
+-----------------------------
+
+You may want your Ansible handlers to use variables. For example, if the name of a service varies slightly by distribution, you want your output to show the exact name of the restarted service for each target machine. Avoid placing variables in the name of the handler. Since handler names are templated early on, Ansible may not have a value available for a handler name like this::
+
+    handlers:
+    # this handler name may cause your play to fail!
+    - name: restart "{{ web_service_name }}"
+
+If the variable used in the handler name is not available, the entire play fails. Changing that variable mid-play **will not** result in newly created handler.
+
+Instead, place variables in the task parameters of your handler. You can load the values using ``include_vars`` like this:
+
+  .. code-block:: yaml+jinja
+
+    tasks:
+      - name: Set host variables based on distribution
+        include_vars: "{{ ansible_facts.distribution }}.yml"
+
+    handlers:
+      - name: restart web service
+        service:
+          name: "{{ web_service_name | default('httpd') }}"
+          state: restarted
+
+Handlers can also "listen" to generic topics, and tasks can notify those topics as follows::
+
+    handlers:
+      - name: restart memcached
+        service:
+          name: memcached
+          state: restarted
+        listen: "restart web services"
+      - name: restart apache
+        service:
+          name: apache
+          state: restarted
+        listen: "restart web services"
+
+    tasks:
+      - name: restart everything
+        command: echo "this task will restart the web services"
+        notify: "restart web services"
+
+This use makes it much easier to trigger multiple handlers. It also decouples handlers from their names,
+making it easier to share handlers among playbooks and roles (especially when using 3rd party roles from
+a shared source like Galaxy).
+
+.. note::
+   * Handlers always run in the order they are defined, not in the order listed in the notify-statement. This is also the case for handlers using `listen`.
+   * Handler names and `listen` topics live in a global namespace.
+   * Handler names are templatable and `listen` topics are not.
+   * Use unique handler names. If you trigger more than one handler with the same name, the first one(s) get overwritten. Only the last one defined will run.
+   * You can notify a handler defined inside a static include.
+   * You cannot notify a handler defined inside a dynamic include.
+
+When using handlers within roles, note that:
+
+* handlers notified within ``pre_tasks``, ``tasks``, and ``post_tasks`` sections are automatically flushed in the end of section where they were notified.
+* handlers notified within ``roles`` section are automatically flushed in the end of ``tasks`` section, but before any ``tasks`` handlers.
+* handlers are play scoped and as such can be used outside of the role they are defined in.

docs/docsite/rst/user_guide/playbooks_intro.rst

@@ -2,7 +2,7 @@
 .. _playbooks_intro:
 
 ******************
-Intro to Playbooks
+Intro to playbooks
 ******************
 
 Ansible Playbooks offer a repeatable, re-usable, simple configuration management and multi-machine deployment system, one that is well suited to deploying complex applications. If you need to execute a task with Ansible more than once, write a playbook and put it under source control. Then you can use the playbook to push out new configuration or confirm the configuration of remote systems. The playbooks in the `ansible-examples repository <https://github.com/ansible/ansible-examples>`_ illustrate many useful techniques. You may want to look at these in another tab as you read the documentation.
@@ -93,138 +93,6 @@ To run your playbook, use the :ref:`ansible-playbook` command::
 
 Use the ``--verbose`` flag when running your playbook to see detailed output from successful modules as well as unsuccessful ones.
 
-.. _handlers:
-
-Handlers: running operations on change
-======================================
-
-Sometimes you want a task to run only when a change is made on a machine. For example, you may want to restart a service if a task updates the configuration of that service, but not if the configuration is unchanged. Ansible uses handlers to address this use case. Handlers are tasks that only run when notified. Each handler should have a globally unique name.
-
-This playbook, ``verify-apache.yml``, contains a single play with variables, the remote user, and a handler::
-
-    ---
-    - name: verify apache installation
-      hosts: webservers
-      vars:
-        http_port: 80
-        max_clients: 200
-      remote_user: root
-      tasks:
-      - name: ensure apache is at the latest version
-        yum:
-          name: httpd
-          state: latest
-      - name: write the apache config file
-        template:
-          src: /srv/httpd.j2
-          dest: /etc/httpd.conf
-        notify:
-        - restart apache
-      - name: ensure apache is running
-        service:
-          name: httpd
-          state: started
-      handlers:
-        - name: restart apache
-          service:
-            name: httpd
-            state: restarted
-
-In the example above, the second task notifies the handler. A single task can notify more than one handler::
-
-    - name: template configuration file
-      template:
-        src: template.j2
-        dest: /etc/foo.conf
-      notify:
-        - restart memcached
-        - restart apache
-      handlers:
-        - name: restart memcached
-          service:
-            name: memcached
-            state: restarted
-        - name: restart apache
-          service:
-            name: apache
-            state: restarted
-
-Controlling when handlers run
------------------------------
-
-By default, handlers run after all the tasks in a particular play have been completed. This approach is efficient, because the handler only runs once, regardless of how many tasks notify it. For example, if multiple tasks update a configuration file and notify a handler to restart Apache, Ansible only bounces Apache once to avoid unnecessary restarts.
-
-If you need handlers to run before the end of the play, add a task to flush them using the :ref:`meta module <meta_module>`, which executes Ansible actions::
-
-    tasks:
-      - shell: some tasks go here
-      - meta: flush_handlers
-      - shell: some other tasks
-
-The ``meta: flush_handlers`` task triggers any handlers that have been notified at that point in the play.
-
-Using variables with handlers
------------------------------
-
-You may want your Ansible handlers to use variables. For example, if the name of a service varies slightly by distribution, you want your output to show the exact name of the restarted service for each target machine. Avoid placing variables in the name of the handler. Since handler names are templated early on, Ansible may not have a value available for a handler name like this::
-
-    handlers:
-    # this handler name may cause your play to fail!
-    - name: restart "{{ web_service_name }}"
-
-If the variable used in the handler name is not available, the entire play fails. Changing that variable mid-play **will not** result in newly created handler.
-
-Instead, place variables in the task parameters of your handler. You can load the values using ``include_vars`` like this:
-
-  .. code-block:: yaml+jinja
-
-    tasks:
-      - name: Set host variables based on distribution
-        include_vars: "{{ ansible_facts.distribution }}.yml"
-
-    handlers:
-      - name: restart web service
-        service:
-          name: "{{ web_service_name | default('httpd') }}"
-          state: restarted
-
-Handlers can also "listen" to generic topics, and tasks can notify those topics as follows::
-
-    handlers:
-      - name: restart memcached
-        service:
-          name: memcached
-          state: restarted
-        listen: "restart web services"
-      - name: restart apache
-        service:
-          name: apache
-          state: restarted
-        listen: "restart web services"
-
-    tasks:
-      - name: restart everything
-        command: echo "this task will restart the web services"
-        notify: "restart web services"
-
-This use makes it much easier to trigger multiple handlers. It also decouples handlers from their names,
-making it easier to share handlers among playbooks and roles (especially when using 3rd party roles from
-a shared source like Galaxy).
-
-.. note::
-   * Handlers always run in the order they are defined, not in the order listed in the notify-statement. This is also the case for handlers using `listen`.
-   * Handler names and `listen` topics live in a global namespace.
-   * Handler names are templatable and `listen` topics are not.
-   * Use unique handler names. If you trigger more than one handler with the same name, the first one(s) get overwritten. Only the last one defined will run.
-   * You can notify a handler defined inside a static include.
-   * You cannot notify a handler defined inside a dynamic include.
-
-When using handlers within roles, note that:
-
-* handlers notified within ``pre_tasks``, ``tasks``, and ``post_tasks`` sections are automatically flushed in the end of section where they were notified.
-* handlers notified within ``roles`` section are automatically flushed in the end of ``tasks`` section, but before any ``tasks`` handlers.
-* handlers are play scoped and as such can be used outside of the role they are defined in.
-
 .. _playbook_ansible-pull:
 
 Ansible-Pull

docs/docsite/rst/user_guide/playbooks_special_topics.rst

@@ -1,27 +1,8 @@
+:orphan:
+
 .. _playbooks_special_topics:
 
-Advanced Playbooks Features
+Advanced playbooks features
 ===========================
 
-As you write more playbooks and roles, you might have some special use cases. For example, you may want to execute "dry runs" of your playbooks (:ref:`check_mode_dry`), ask playbook users to supply information (:ref:`playbooks_prompts`), retrieve information from an external datastore or API (:ref:`lookup_plugins`), or change the way Ansible handles failures (:ref:`playbooks_error_handling`). The topics listed on this page cover these use cases and many more. If you cannot achieve your goals with basic Ansible concepts and actions, browse through these topics for help with your use case.
-
-.. toctree::
-   :maxdepth: 1
-
-   become
-   playbooks_async
-   playbooks_checkmode
-   playbooks_debugger
-   playbooks_delegation
-   playbooks_environment
-   playbooks_error_handling
-   playbooks_advanced_syntax
-   complex_data_manipulation
-   ../plugins/plugins
-   playbooks_prompts
-   playbooks_tags
-   vault
-   playbooks_startnstep
-   ../reference_appendices/playbooks_keywords
-   playbooks_lookups
-   playbooks_module_defaults
+This page is obsolete. Refer to the :ref:`main User Guide index page <user_guide_index>` for links to all playbook-related topics. Please update any links you may have made directly to this page.