From 913716547bbb2701d1bb3078ef89783ba0e4de98 Mon Sep 17 00:00:00 2001 From: Alicia Cozine <879121+acozine@users.noreply.github.com> Date: Mon, 9 Mar 2020 13:56:15 -0500 Subject: fix last 7 docs errors on post-migration test runs (#68115) * address toc-tree-glob-pattern-no-match errors * address Include-file-not-found error * address 2.10 porting guide errors, add warning to page * updates individual plugin type pages * Add ignores. Co-authored-by: Alicia Cozine Co-authored-by: Matt Clay --- .../rst/dev_guide/developing_modules_general_windows.rst | 10 ++-------- docs/docsite/rst/plugins/cliconf.rst | 13 +++++-------- docs/docsite/rst/plugins/httpapi.rst | 14 +++++--------- docs/docsite/rst/plugins/netconf.rst | 16 ++++++---------- docs/docsite/rst/plugins/plugins.rst | 3 --- docs/docsite/rst/porting_guides/porting_guide_2.10.rst | 14 ++++++++++---- test/sanity/ignore.txt | 3 +++ 7 files changed, 31 insertions(+), 42 deletions(-) diff --git a/docs/docsite/rst/dev_guide/developing_modules_general_windows.rst b/docs/docsite/rst/dev_guide/developing_modules_general_windows.rst index 8ac00d3bf4..8ec4ed1965 100644 --- a/docs/docsite/rst/dev_guide/developing_modules_general_windows.rst +++ b/docs/docsite/rst/dev_guide/developing_modules_general_windows.rst @@ -182,15 +182,9 @@ When creating a new module there are a few things to keep in mind: - Use the full cmdlet name instead of aliases, e.g. ``Remove-Item`` over ``rm`` - Use named parameters with cmdlets, e.g. ``Remove-Item -Path C:\temp`` over ``Remove-Item C:\temp`` -A very basic powershell module `win_environment `_ is included below. It demonstrates how to implement check-mode and diff-support, and also shows a warning to the user when a specific condition is met. +A very basic Powershell module `win_environment `_ incorporates best practices for Powershell modules. It demonstrates how to implement check-mode and diff-support, and also shows a warning to the user when a specific condition is met. -.. .. include:: ../../../../lib/ansible/modules/windows/win_environment.ps1 -.. :code: powershell - -.. literalinclude:: ../../../../lib/ansible/modules/windows/win_environment.ps1 - :language: powershell - -A slightly more advanced module is `win_uri `_ which additionally shows how to use different parameter types (bool, str, int, list, dict, path) and a selection of choices for parameters, how to fail a module and how to handle exceptions. +A slightly more advanced module is `win_uri `_ which additionally shows how to use different parameter types (bool, str, int, list, dict, path) and a selection of choices for parameters, how to fail a module and how to handle exceptions. As part of the new ``AnsibleModule`` wrapper, the input parameters are defined and validated based on an argument spec. The following options can be set at the root level of the argument spec: diff --git a/docs/docsite/rst/plugins/cliconf.rst b/docs/docsite/rst/plugins/cliconf.rst index a0bee4da79..1d888c6b6c 100644 --- a/docs/docsite/rst/plugins/cliconf.rst +++ b/docs/docsite/rst/plugins/cliconf.rst @@ -7,6 +7,10 @@ Cliconf Plugins :local: :depth: 2 +.. warning:: + + Links on this page may not point to the most recent versions of plugins. In preparation for the release of 2.10, many plugins and modules have migrated to Collections on `Ansible Galaxy `_. For the current development status of Collections and FAQ see `Ansible Collections Community Guide `_. + Cliconf plugins are abstractions over the CLI interface to network devices. They provide a standard interface for Ansible to execute tasks on those network devices. @@ -37,14 +41,7 @@ Plugins are self-documenting. Each plugin should document its configuration opti Plugin list ----------- -You can use ``ansible-doc -t cliconf -l`` to see the list of available plugins. -Use ``ansible-doc -t cliconf `` to see detailed documentation and examples. - - -.. toctree:: :maxdepth: 1 - :glob: - - cliconf/* +These plugins have migrated to a collection. Updates on where to find and how to use them will be coming soon. .. seealso:: diff --git a/docs/docsite/rst/plugins/httpapi.rst b/docs/docsite/rst/plugins/httpapi.rst index 1136bab49a..1b5554d142 100644 --- a/docs/docsite/rst/plugins/httpapi.rst +++ b/docs/docsite/rst/plugins/httpapi.rst @@ -7,6 +7,10 @@ Httpapi Plugins :local: :depth: 2 +.. warning:: + + Links on this page may not point to the most recent versions of plugins. In preparation for the release of 2.10, many plugins and modules have migrated to Collections on `Ansible Galaxy `_. For the current development status of Collections and FAQ see `Ansible Collections Community Guide `_. + Httpapi plugins tell Ansible how to interact with a remote device's HTTP-based API and execute tasks on the device. @@ -58,15 +62,7 @@ See the full working example at https://github.com/network-automation/httpapi. Plugin List ----------- -You can use ``ansible-doc -t httpapi -l`` to see the list of available plugins. -Use ``ansible-doc -t httpapi `` to see detailed documentation and examples. - - -.. toctree:: :maxdepth: 1 - :glob: - - httpapi/* - +These plugins have migrated to a collection. Updates on where to find and how to use them will be coming soon. .. seealso:: diff --git a/docs/docsite/rst/plugins/netconf.rst b/docs/docsite/rst/plugins/netconf.rst index 103a6af174..6611dbd41a 100644 --- a/docs/docsite/rst/plugins/netconf.rst +++ b/docs/docsite/rst/plugins/netconf.rst @@ -7,8 +7,11 @@ Netconf Plugins :local: :depth: 2 -Netconf plugins are abstractions over the Netconf interface to network devices. They provide a standard interface -for Ansible to execute tasks on those network devices. +.. warning:: + + Links on this page may not point to the most recent versions of plugins. In preparation for the release of 2.10, many plugins and modules have migrated to Collections on `Ansible Galaxy `_. For the current development status of Collections and FAQ see `Ansible Collections Community Guide `_. + +Netconf plugins are abstractions over the Netconf interface to network devices. They provide a standard interface for Ansible to execute tasks on those network devices. These plugins generally correspond one-to-one to network device platforms. The appropriate netconf plugin will thus be automatically loaded based on the ``ansible_network_os`` variable. If the platform supports standard @@ -42,14 +45,7 @@ Plugins are self-documenting. Each plugin should document its configuration opti Plugin list ----------- -You can use ``ansible-doc -t netconf -l`` to see the list of available plugins. -Use ``ansible-doc -t netconf `` to see detailed documentation and examples. - - -.. toctree:: :maxdepth: 1 - :glob: - - netconf/* +These plugins have migrated to a collection. Updates on where to find and how to use them will be coming soon. .. seealso:: diff --git a/docs/docsite/rst/plugins/plugins.rst b/docs/docsite/rst/plugins/plugins.rst index 4dee6c6a27..052884d64e 100644 --- a/docs/docsite/rst/plugins/plugins.rst +++ b/docs/docsite/rst/plugins/plugins.rst @@ -17,12 +17,9 @@ This section covers the various types of plugins that are included with Ansible: become cache callback - cliconf connection - httpapi inventory lookup - netconf shell strategy vars diff --git a/docs/docsite/rst/porting_guides/porting_guide_2.10.rst b/docs/docsite/rst/porting_guides/porting_guide_2.10.rst index a45defd615..c0aec37147 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_2.10.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_2.10.rst @@ -5,6 +5,10 @@ Ansible 2.10 Porting Guide ************************** +.. warning:: + + Links on this page may not point to the most recent versions of modules. In preparation for the release of 2.10, many plugins and modules have migrated to Collections on `Ansible Galaxy `_. For the current development status of Collections and FAQ see `Ansible Collections Community Guide `_. We expect the 2.10 Porting Guide to change frequently up to the 2.10 release. Follow the conversations about collections on our various :ref:`communication` channels for the latest information on the status of the ``devel`` branch. + This section discusses the behavioral changes between Ansible 2.9 and Ansible 2.10. It is intended to assist in updating your playbooks, plugins and other parts of your Ansible infrastructure so they will work with this version of Ansible. @@ -39,6 +43,9 @@ Deprecated Modules ======= +.. warning:: + + Links on this page may not point to the most recent versions of modules. We will update them when we can. Modules removed --------------- @@ -53,9 +60,8 @@ Deprecation notices The following modules will be removed in Ansible 2.14. Please update your playbooks accordingly. -* ldap_attr use :ref:`ldap_attrs ` instead. -* vyos_static_route use :ref:`vyos_static_routes ` instead. - +* ldap_attr use ldap_attrs instead. +* vyos_static_route use vyos_static_routes instead. The following functionality will be removed in Ansible 2.14. Please update update your playbooks accordingly. @@ -95,7 +101,7 @@ The following functionality will change in Ansible 2.14. Please update update yo The following modules will be removed in Ansible 2.14. Please update your playbooks accordingly. -* ``vmware_dns_config`` use :ref:`vmware_host_dns ` instead. +* ``vmware_dns_config`` use vmware_host_dns instead. Noteworthy module changes diff --git a/test/sanity/ignore.txt b/test/sanity/ignore.txt index 3df2d81401..82dcacd170 100644 --- a/test/sanity/ignore.txt +++ b/test/sanity/ignore.txt @@ -7,6 +7,9 @@ docs/docsite/_themes/sphinx_rtd_theme/__init__.py metaclass-boilerplate docs/docsite/rst/conf.py future-import-boilerplate docs/docsite/rst/conf.py metaclass-boilerplate docs/docsite/rst/dev_guide/testing/sanity/no-smart-quotes.rst no-smart-quotes +docs/docsite/rst/plugins/cliconf.rst docs-build +docs/docsite/rst/plugins/httpapi.rst docs-build +docs/docsite/rst/plugins/netconf.rst docs-build examples/scripts/ConfigureRemotingForAnsible.ps1 pslint:PSCustomUseLiteralPath examples/scripts/upgrade_to_ps3.ps1 pslint:PSCustomUseLiteralPath examples/scripts/upgrade_to_ps3.ps1 pslint:PSUseApprovedVerbs -- cgit v1.2.1