From 224a0b48097f8344e885158f9858bc29b21bf518 Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Fri, 31 Jul 2020 16:51:54 -0400 Subject: [PATCH] [DOCS] Backportapalooza 5 (#70999) * misc typo fixes (#70736) Signed-off-by: Abhijeet Kasurde (cherry picked from commit 8915f262b491055b95c3faf7ce911be95fd4514c) * How to use rst :ref: for modules in collections (#70567) (cherry picked from commit 748ba96610f7d1e05c117a084e2de1023fb09d0b) * Update network_best_practices_2.5.rst (#70962) Fix a small typo in the playbook tasks sample section (cherry picked from commit 69e5c6c14a9a5d694b657cfb24c2cc71f3d8fbdb) * Fix a typo in "restart mysql" example (#70950) Fix a typo in "restart mysql" example task. It's missing a space between "state:" and "restarted". (cherry picked from commit 37e9d2278aac698124eb8000cd332c09ba1393d9) Co-authored-by: Abhijeet Kasurde Co-authored-by: PJ Waskiewicz Co-authored-by: Emilien Macchi --- .../rst/dev_guide/style_guide/index.rst | 28 ++++++++++++++++--- .../user_guide/network_best_practices_2.5.rst | 2 +- .../rst/user_guide/playbooks_reuse.rst | 2 +- examples/hosts | 2 +- examples/play.yml | 12 ++++---- lib/ansible/executor/task_executor.py | 4 +-- 6 files changed, 35 insertions(+), 15 deletions(-) diff --git a/docs/docsite/rst/dev_guide/style_guide/index.rst b/docs/docsite/rst/dev_guide/style_guide/index.rst index 975fd17a126..a50a3180e90 100644 --- a/docs/docsite/rst/dev_guide/style_guide/index.rst +++ b/docs/docsite/rst/dev_guide/style_guide/index.rst @@ -171,13 +171,33 @@ The second example adds custom text for the link. Adding links to modules and plugins ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -* Module links use the module name followed by ``_module`` for the anchor. -* Plugin links use the plugin name followed by the plugin type. For example, :ref:`enable become plugin `). +Ansible 2.10 and later require the extended Fully Qualified Collection Name (FQCN) as part of the links: + +.. code-block:: text + + ansible_collections. + FQCN + _module + +For example: + + .. code-block:: rst + + :ref:`ansible.builtin.first_found lookup plugin ` + +displays as :ref:`ansible.builtin.first_found lookup plugin `. + +Modules require different suffixes from other plugins: + +* Module links use this extended FQCN module name with ``_module`` for the anchor. +* Plugin links use this extended FQCN plugin name with the plugin type (``_connection`` for example). .. code-block:: rst - :ref:`this module `` - :ref:`that connection plugin ` + :ref:`arista.eos.eos_config ` + :ref:`community.kubernetes.kubectl connection plugin ` + +.. note:: + + ``ansible.builtin`` is the FQCN for modules included in ``ansible.base``. Documentation links are the only place you prepend ``ansible_collections`` to the FQCN. This is used by the documentation build scripts to correctly fetch documentation from collections on Ansible Galaxy. .. _local_toc: diff --git a/docs/docsite/rst/network/user_guide/network_best_practices_2.5.rst b/docs/docsite/rst/network/user_guide/network_best_practices_2.5.rst index 5cb5ab209bb..33a2fe46b0a 100644 --- a/docs/docsite/rst/network/user_guide/network_best_practices_2.5.rst +++ b/docs/docsite/rst/network/user_guide/network_best_practices_2.5.rst @@ -201,7 +201,7 @@ Next, create a playbook file called ``facts-demo.yml`` containing the following: eos_facts: when: ansible_network_os == 'eos' - - name: Gather facts (ops) + - name: Gather facts (ios) ios_facts: when: ansible_network_os == 'ios' diff --git a/docs/docsite/rst/user_guide/playbooks_reuse.rst b/docs/docsite/rst/user_guide/playbooks_reuse.rst index 5331b4866c4..ef9863212d7 100644 --- a/docs/docsite/rst/user_guide/playbooks_reuse.rst +++ b/docs/docsite/rst/user_guide/playbooks_reuse.rst @@ -137,7 +137,7 @@ You can also use includes and imports in the :ref:`handlers` section of a playbo - name: restart mysql service: name: mysql - state:restarted + state: restarted You can trigger handlers from either an import or an include, but the procedure is different for each method of re-use. If you include the file, you must notify the include itself, which triggers all the tasks in ``restarts.yml``. If you import the file, you must notify the individual task(s) within ``restarts.yml``. You can mix direct tasks and handlers with included or imported tasks and handlers. diff --git a/examples/hosts b/examples/hosts index 8e35d5dd3b6..e84a30cd984 100644 --- a/examples/hosts +++ b/examples/hosts @@ -31,7 +31,7 @@ # Ex 3: A collection of database servers in the 'dbservers' group: ## [dbservers] -## +## ## db01.intranet.mydomain.net ## db02.intranet.mydomain.net ## 10.25.1.56 diff --git a/examples/play.yml b/examples/play.yml index 0fb6a3e18f7..b0dee7d757f 100644 --- a/examples/play.yml +++ b/examples/play.yml @@ -69,7 +69,7 @@ # maintenance tasks, and other cases where you want to run the playbook # against just a few systems rather than a whole group. # Note that the variable cannot be set in inventory, since we need to know the hosts - # before we can use invenotry variables. So normally 'extra vars' are used, as you can + # before we can use inventory variables. So normally 'extra vars' are used, as you can # see below. # # If you set hosts as shown above, then you can specify which hosts to @@ -102,7 +102,7 @@ remote_user: login_user ########### # Play keyword: user - # Default: depends on conneciton plugin, for ssh it is 'current user executing Ansible' + # Default: depends on connection plugin, for ssh it is 'current user executing Ansible' # Required: no # Description: # Remote user to login on remote targets and 'normally' execute the tasks as @@ -113,7 +113,7 @@ # Default: False # Required: no # Description: - # If True, always use privilege escalationj to run tasks from this play, just like passing the + # If True, always use privilege escalation to run tasks from this play, just like passing the # --become flag to ansible or ansible-playbook. @@ -124,7 +124,7 @@ # Required: no # Description: # When using privilege escalation this is the user you 'become' after login with the remote_user - # for examplle you login to the remote as 'login_user' then you 'become' root to execute the tasks + # for example you login to the remote as 'login_user' then you 'become' root to execute the tasks become_method: sudo ########### @@ -141,8 +141,8 @@ # Default: ssh # Required: no # Description: - # This sets which connection plugin Asnible will use to try to communicate with the target host. - # notable options are paramiko (python implementation of ssh, mostly useful in corener cases in which the ssh cli + # This sets which connection plugin Ansible will use to try to communicate with the target host. + # notable options are paramiko (python implementation of ssh, mostly useful in corner cases in which the ssh cli # does not work well with the target. Also 'local' which forces a 'local fork' to execute the task, but normally # what you really want is `delegate_to: localhost` see examples below in 'Run things locally!' entry. # use `ansible-doc -t connection -l` to list all the options. diff --git a/lib/ansible/executor/task_executor.py b/lib/ansible/executor/task_executor.py index 63b1a7b4cad..573e09a2d02 100644 --- a/lib/ansible/executor/task_executor.py +++ b/lib/ansible/executor/task_executor.py @@ -898,9 +898,9 @@ class TaskExecutor: else: self._play_context.connection = self._task.connection - # TODO: play context has logic to update the conneciton for 'smart' + # TODO: play context has logic to update the connection for 'smart' # (default value, will chose between ssh and paramiko) and 'persistent' - # (really paramiko), evnentually this should move to task object itself. + # (really paramiko), eventually this should move to task object itself. connection_name = self._play_context.connection # load connection