diff --git a/.github/BOTMETA.yml b/.github/BOTMETA.yml index 915896234c..55e6c641b9 100644 --- a/.github/BOTMETA.yml +++ b/.github/BOTMETA.yml @@ -1025,6 +1025,28 @@ files: labels: - windows ############################### +# plugins/doc_fragments + $plugins/doc_fragments/: + support: community + $plugins/doc_fragments/__init__.py: + support: core + $plugins/doc_fragments/aci.py: *aci + $plugins/doc_fragments/acme.py: + maintainers: resmo felixfontein + $plugins/doc_fragments/cloudstack.py: + maintainers: $team_cloudstack + labels: cloudstack + $plugins/doc_fragments/docker.py: + support: community + maintainers: $team_docker + supershipit: felixfontein + $plugins/doc_fragments/mso.py: *aci + $plugins/doc_fragments/vultr.py: + maintainers: $team_vultr + labels: cloud + $plugins/doc_fragments/xenserver.py: + maintainers: bvitnik +############################### # plugins/filter $plugins/filter/: support: community @@ -1211,24 +1233,6 @@ files: keywords: - jinja - jinja2 - lib/ansible/utils/module_docs_fragments/: - support: community - lib/ansible/utils/module_docs_fragments/aci.py: *aci - lib/ansible/utils/module_docs_fragments/acme.py: - maintainers: resmo felixfontein - lib/ansible/utils/module_docs_fragments/docker.py: - support: community - maintainers: $team_docker - supershipit: felixfontein - lib/ansible/utils/module_docs_fragments/mso.py: *aci - lib/ansible/utils/module_docs_fragments/xenserver.py: - maintainers: bvitnik - lib/ansible/utils/module_docs_fragments/cloudstack.py: - maintainers: $team_cloudstack - labels: cloudstack - lib/ansible/utils/module_docs_fragments/vultr.py: - maintainers: $team_vultr - labels: cloud test/sanity/validate-modules: notified: - mattclay diff --git a/docs/docsite/rst/dev_guide/developing_modules_documenting.rst b/docs/docsite/rst/dev_guide/developing_modules_documenting.rst index 6c86046701..1613567ed3 100644 --- a/docs/docsite/rst/dev_guide/developing_modules_documenting.rst +++ b/docs/docsite/rst/dev_guide/developing_modules_documenting.rst @@ -272,7 +272,14 @@ You can link from your module documentation to other module docs, other resource Documentation fragments ----------------------- -If you're writing multiple related modules, they may share common documentation, such as authentication details or file mode settings. Rather than duplicate that information in each module's ``DOCUMENTATION`` block, you can save it once as a fragment and use it in each module's documentation. Shared documentation fragments are contained in a ``ModuleDocFragment`` class in `lib/ansible/utils/module_docs_fragments/ `_. To include a documentation fragment, add ``extends_documentation_fragment: FRAGMENT_NAME`` in your module's documentation. +If you're writing multiple related modules, they may share common documentation, such as authentication details or file mode settings. Rather than duplicate that information in each module's ``DOCUMENTATION`` block, you can save it once as a doc_fragment plugin and use it in each module's documentation. In Ansible, shared documentation fragments are contained in a ``ModuleDocFragment`` class in `lib/ansible/plugins/doc_fragments/ `_. To include a documentation fragment, add ``extends_documentation_fragment: FRAGMENT_NAME`` in your module's documentation. + +.. _note: + * in 2.8 the Ansible directories for doc fragments changed, see documentation of previous versions to find the old locations. + +.. versionadded:: 2.8 + +Since version 2.8, you can have user supplied doc_fragments by using a ``doc_fragments`` directory adjacent to play or role, just like any other plugin. For example, all AWS modules should include:: diff --git a/docs/docsite/rst/dev_guide/developing_modules_in_groups.rst b/docs/docsite/rst/dev_guide/developing_modules_in_groups.rst index e9c383fbab..89d32ccadc 100644 --- a/docs/docsite/rst/dev_guide/developing_modules_in_groups.rst +++ b/docs/docsite/rst/dev_guide/developing_modules_in_groups.rst @@ -28,7 +28,7 @@ Although it's tempting to get straight into coding, there are a few things to be * Starting with Ansible version 2.7, all new modules must :ref:`support Python 2.7+ and Python 3.5+ `. If this is an issue, please contact us (see the "Speak to us" section later in this document to learn how). * Have a look at the existing modules and how they've been named in the :ref:`all_modules`, especially in the same functional area (such as cloud, networking, databases). * Shared code can be placed into ``lib/ansible/module_utils/`` -* Shared documentation (for example describing common arguments) can be placed in ``lib/ansible/utils/module_docs_fragments/``. +* Shared documentation (for example describing common arguments) can be placed in ``lib/ansible/plugins/doc_fragments/``. * With great power comes great responsibility: Ansible module maintainers have a duty to help keep modules up to date. As with all successful community projects, module maintainers should keep a watchful eye for reported issues and contributions. * Although not required, unit and/or integration tests are strongly recommended. Unit tests are especially valuable when external resources (such as cloud or network devices) are required. For more information see :doc:`testing` and the `Testing Working Group `_. * Starting with Ansible 2.4 all :ref:`network_modules` MUST have unit tests. @@ -81,7 +81,7 @@ The first PR is slightly different to the rest because it: * defines the namespace * provides a basis for detailed review that will help shape your future PRs -* may include shared documentation (`docs_fragments`) that multiple modules require +* may include shared documentation (`doc_fragments`) that multiple modules require * may include shared code (`module_utils`) that multiple modules require @@ -89,7 +89,7 @@ The first PR should include the following files: * ``lib/ansible/modules/$category/$topic/__init__.py`` - An empty file to initialize namespace and allow Python to import the files. *Required new file* * ``lib/ansible/modules/$category/$topic/$yourfirstmodule.py`` - A single module. *Required new file* -* ``lib/ansible/utils/module_docs_fragments/$topic.py`` - Code documentation, such as details regarding common arguments. *Optional new file* +* ``lib/ansible/plugins/doc_fragments/$topic.py`` - Code documentation, such as details regarding common arguments. *Optional new file* * ``lib/ansible/module_utils/$topic.py`` - Code shared between more than one module, such as common arguments. *Optional new file* * ``docs/docsite/rst/dev_guide/developing_module_utilities.rst`` - Document your new `module_utils` file. *Optional update to existing file* diff --git a/lib/ansible/config/base.yml b/lib/ansible/config/base.yml index 5d5630d7c3..60d59ef90d 100644 --- a/lib/ansible/config/base.yml +++ b/lib/ansible/config/base.yml @@ -352,6 +352,14 @@ LOCALHOST_WARNING: - {key: localhost_warning, section: defaults} type: boolean version_added: "2.6" +DOC_FRAGMENT_PLUGIN_PATH: + name: documentation fragment plugins path + default: ~/.ansible/plugins/doc_fragments:/usr/share/ansible/plugins/doc_fragments + description: Colon separated paths in which Ansible will search for Documentation Fragments Plugins. + env: [{name: ANSIBLE_DOC_FRAGMENT_PLUGINS}] + ini: + - {key: doc_fragment_plugins, section: defaults} + type: pathspec DEFAULT_ACTION_PLUGIN_PATH: name: Action plugins path default: ~/.ansible/plugins/action:/usr/share/ansible/plugins/action diff --git a/lib/ansible/utils/module_docs_fragments/__init__.py b/lib/ansible/plugins/doc_fragments/__init__.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/__init__.py rename to lib/ansible/plugins/doc_fragments/__init__.py diff --git a/lib/ansible/utils/module_docs_fragments/a10.py b/lib/ansible/plugins/doc_fragments/a10.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/a10.py rename to lib/ansible/plugins/doc_fragments/a10.py diff --git a/lib/ansible/utils/module_docs_fragments/aci.py b/lib/ansible/plugins/doc_fragments/aci.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/aci.py rename to lib/ansible/plugins/doc_fragments/aci.py diff --git a/lib/ansible/utils/module_docs_fragments/acme.py b/lib/ansible/plugins/doc_fragments/acme.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/acme.py rename to lib/ansible/plugins/doc_fragments/acme.py diff --git a/lib/ansible/utils/module_docs_fragments/aireos.py b/lib/ansible/plugins/doc_fragments/aireos.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/aireos.py rename to lib/ansible/plugins/doc_fragments/aireos.py diff --git a/lib/ansible/utils/module_docs_fragments/alicloud.py b/lib/ansible/plugins/doc_fragments/alicloud.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/alicloud.py rename to lib/ansible/plugins/doc_fragments/alicloud.py diff --git a/lib/ansible/utils/module_docs_fragments/aruba.py b/lib/ansible/plugins/doc_fragments/aruba.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/aruba.py rename to lib/ansible/plugins/doc_fragments/aruba.py diff --git a/lib/ansible/utils/module_docs_fragments/asa.py b/lib/ansible/plugins/doc_fragments/asa.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/asa.py rename to lib/ansible/plugins/doc_fragments/asa.py diff --git a/lib/ansible/utils/module_docs_fragments/auth_basic.py b/lib/ansible/plugins/doc_fragments/auth_basic.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/auth_basic.py rename to lib/ansible/plugins/doc_fragments/auth_basic.py diff --git a/lib/ansible/utils/module_docs_fragments/avi.py b/lib/ansible/plugins/doc_fragments/avi.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/avi.py rename to lib/ansible/plugins/doc_fragments/avi.py diff --git a/lib/ansible/utils/module_docs_fragments/aws.py b/lib/ansible/plugins/doc_fragments/aws.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/aws.py rename to lib/ansible/plugins/doc_fragments/aws.py diff --git a/lib/ansible/utils/module_docs_fragments/aws_credentials.py b/lib/ansible/plugins/doc_fragments/aws_credentials.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/aws_credentials.py rename to lib/ansible/plugins/doc_fragments/aws_credentials.py diff --git a/lib/ansible/utils/module_docs_fragments/azure.py b/lib/ansible/plugins/doc_fragments/azure.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/azure.py rename to lib/ansible/plugins/doc_fragments/azure.py diff --git a/lib/ansible/utils/module_docs_fragments/azure_tags.py b/lib/ansible/plugins/doc_fragments/azure_tags.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/azure_tags.py rename to lib/ansible/plugins/doc_fragments/azure_tags.py diff --git a/lib/ansible/utils/module_docs_fragments/backup.py b/lib/ansible/plugins/doc_fragments/backup.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/backup.py rename to lib/ansible/plugins/doc_fragments/backup.py diff --git a/lib/ansible/utils/module_docs_fragments/ce.py b/lib/ansible/plugins/doc_fragments/ce.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/ce.py rename to lib/ansible/plugins/doc_fragments/ce.py diff --git a/lib/ansible/utils/module_docs_fragments/cloudstack.py b/lib/ansible/plugins/doc_fragments/cloudstack.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/cloudstack.py rename to lib/ansible/plugins/doc_fragments/cloudstack.py diff --git a/lib/ansible/utils/module_docs_fragments/cnos.py b/lib/ansible/plugins/doc_fragments/cnos.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/cnos.py rename to lib/ansible/plugins/doc_fragments/cnos.py diff --git a/lib/ansible/utils/module_docs_fragments/constructed.py b/lib/ansible/plugins/doc_fragments/constructed.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/constructed.py rename to lib/ansible/plugins/doc_fragments/constructed.py diff --git a/lib/ansible/utils/module_docs_fragments/decrypt.py b/lib/ansible/plugins/doc_fragments/decrypt.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/decrypt.py rename to lib/ansible/plugins/doc_fragments/decrypt.py diff --git a/lib/ansible/utils/module_docs_fragments/default_callback.py b/lib/ansible/plugins/doc_fragments/default_callback.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/default_callback.py rename to lib/ansible/plugins/doc_fragments/default_callback.py diff --git a/lib/ansible/utils/module_docs_fragments/dellos10.py b/lib/ansible/plugins/doc_fragments/dellos10.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/dellos10.py rename to lib/ansible/plugins/doc_fragments/dellos10.py diff --git a/lib/ansible/utils/module_docs_fragments/dellos6.py b/lib/ansible/plugins/doc_fragments/dellos6.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/dellos6.py rename to lib/ansible/plugins/doc_fragments/dellos6.py diff --git a/lib/ansible/utils/module_docs_fragments/dellos9.py b/lib/ansible/plugins/doc_fragments/dellos9.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/dellos9.py rename to lib/ansible/plugins/doc_fragments/dellos9.py diff --git a/lib/ansible/utils/module_docs_fragments/digital_ocean.py b/lib/ansible/plugins/doc_fragments/digital_ocean.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/digital_ocean.py rename to lib/ansible/plugins/doc_fragments/digital_ocean.py diff --git a/lib/ansible/utils/module_docs_fragments/dimensiondata.py b/lib/ansible/plugins/doc_fragments/dimensiondata.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/dimensiondata.py rename to lib/ansible/plugins/doc_fragments/dimensiondata.py diff --git a/lib/ansible/utils/module_docs_fragments/dimensiondata_wait.py b/lib/ansible/plugins/doc_fragments/dimensiondata_wait.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/dimensiondata_wait.py rename to lib/ansible/plugins/doc_fragments/dimensiondata_wait.py diff --git a/lib/ansible/utils/module_docs_fragments/docker.py b/lib/ansible/plugins/doc_fragments/docker.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/docker.py rename to lib/ansible/plugins/doc_fragments/docker.py diff --git a/lib/ansible/utils/module_docs_fragments/ec2.py b/lib/ansible/plugins/doc_fragments/ec2.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/ec2.py rename to lib/ansible/plugins/doc_fragments/ec2.py diff --git a/lib/ansible/utils/module_docs_fragments/emc.py b/lib/ansible/plugins/doc_fragments/emc.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/emc.py rename to lib/ansible/plugins/doc_fragments/emc.py diff --git a/lib/ansible/utils/module_docs_fragments/enos.py b/lib/ansible/plugins/doc_fragments/enos.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/enos.py rename to lib/ansible/plugins/doc_fragments/enos.py diff --git a/lib/ansible/utils/module_docs_fragments/eos.py b/lib/ansible/plugins/doc_fragments/eos.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/eos.py rename to lib/ansible/plugins/doc_fragments/eos.py diff --git a/lib/ansible/utils/module_docs_fragments/exoscale.py b/lib/ansible/plugins/doc_fragments/exoscale.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/exoscale.py rename to lib/ansible/plugins/doc_fragments/exoscale.py diff --git a/lib/ansible/utils/module_docs_fragments/f5.py b/lib/ansible/plugins/doc_fragments/f5.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/f5.py rename to lib/ansible/plugins/doc_fragments/f5.py diff --git a/lib/ansible/utils/module_docs_fragments/files.py b/lib/ansible/plugins/doc_fragments/files.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/files.py rename to lib/ansible/plugins/doc_fragments/files.py diff --git a/lib/ansible/utils/module_docs_fragments/fortios.py b/lib/ansible/plugins/doc_fragments/fortios.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/fortios.py rename to lib/ansible/plugins/doc_fragments/fortios.py diff --git a/lib/ansible/utils/module_docs_fragments/gcp.py b/lib/ansible/plugins/doc_fragments/gcp.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/gcp.py rename to lib/ansible/plugins/doc_fragments/gcp.py diff --git a/lib/ansible/utils/module_docs_fragments/ibm_storage.py b/lib/ansible/plugins/doc_fragments/ibm_storage.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/ibm_storage.py rename to lib/ansible/plugins/doc_fragments/ibm_storage.py diff --git a/lib/ansible/utils/module_docs_fragments/infinibox.py b/lib/ansible/plugins/doc_fragments/infinibox.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/infinibox.py rename to lib/ansible/plugins/doc_fragments/infinibox.py diff --git a/lib/ansible/utils/module_docs_fragments/influxdb.py b/lib/ansible/plugins/doc_fragments/influxdb.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/influxdb.py rename to lib/ansible/plugins/doc_fragments/influxdb.py diff --git a/lib/ansible/utils/module_docs_fragments/ingate.py b/lib/ansible/plugins/doc_fragments/ingate.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/ingate.py rename to lib/ansible/plugins/doc_fragments/ingate.py diff --git a/lib/ansible/utils/module_docs_fragments/inventory_cache.py b/lib/ansible/plugins/doc_fragments/inventory_cache.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/inventory_cache.py rename to lib/ansible/plugins/doc_fragments/inventory_cache.py diff --git a/lib/ansible/utils/module_docs_fragments/ios.py b/lib/ansible/plugins/doc_fragments/ios.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/ios.py rename to lib/ansible/plugins/doc_fragments/ios.py diff --git a/lib/ansible/utils/module_docs_fragments/iosxr.py b/lib/ansible/plugins/doc_fragments/iosxr.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/iosxr.py rename to lib/ansible/plugins/doc_fragments/iosxr.py diff --git a/lib/ansible/utils/module_docs_fragments/ipa.py b/lib/ansible/plugins/doc_fragments/ipa.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/ipa.py rename to lib/ansible/plugins/doc_fragments/ipa.py diff --git a/lib/ansible/utils/module_docs_fragments/ironware.py b/lib/ansible/plugins/doc_fragments/ironware.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/ironware.py rename to lib/ansible/plugins/doc_fragments/ironware.py diff --git a/lib/ansible/utils/module_docs_fragments/junos.py b/lib/ansible/plugins/doc_fragments/junos.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/junos.py rename to lib/ansible/plugins/doc_fragments/junos.py diff --git a/lib/ansible/utils/module_docs_fragments/k8s_auth_options.py b/lib/ansible/plugins/doc_fragments/k8s_auth_options.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/k8s_auth_options.py rename to lib/ansible/plugins/doc_fragments/k8s_auth_options.py diff --git a/lib/ansible/utils/module_docs_fragments/k8s_name_options.py b/lib/ansible/plugins/doc_fragments/k8s_name_options.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/k8s_name_options.py rename to lib/ansible/plugins/doc_fragments/k8s_name_options.py diff --git a/lib/ansible/utils/module_docs_fragments/k8s_resource_options.py b/lib/ansible/plugins/doc_fragments/k8s_resource_options.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/k8s_resource_options.py rename to lib/ansible/plugins/doc_fragments/k8s_resource_options.py diff --git a/lib/ansible/utils/module_docs_fragments/k8s_scale_options.py b/lib/ansible/plugins/doc_fragments/k8s_scale_options.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/k8s_scale_options.py rename to lib/ansible/plugins/doc_fragments/k8s_scale_options.py diff --git a/lib/ansible/utils/module_docs_fragments/k8s_state_options.py b/lib/ansible/plugins/doc_fragments/k8s_state_options.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/k8s_state_options.py rename to lib/ansible/plugins/doc_fragments/k8s_state_options.py diff --git a/lib/ansible/utils/module_docs_fragments/keycloak.py b/lib/ansible/plugins/doc_fragments/keycloak.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/keycloak.py rename to lib/ansible/plugins/doc_fragments/keycloak.py diff --git a/lib/ansible/utils/module_docs_fragments/ldap.py b/lib/ansible/plugins/doc_fragments/ldap.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/ldap.py rename to lib/ansible/plugins/doc_fragments/ldap.py diff --git a/lib/ansible/utils/module_docs_fragments/lxca_common.py b/lib/ansible/plugins/doc_fragments/lxca_common.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/lxca_common.py rename to lib/ansible/plugins/doc_fragments/lxca_common.py diff --git a/lib/ansible/utils/module_docs_fragments/manageiq.py b/lib/ansible/plugins/doc_fragments/manageiq.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/manageiq.py rename to lib/ansible/plugins/doc_fragments/manageiq.py diff --git a/lib/ansible/utils/module_docs_fragments/meraki.py b/lib/ansible/plugins/doc_fragments/meraki.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/meraki.py rename to lib/ansible/plugins/doc_fragments/meraki.py diff --git a/lib/ansible/utils/module_docs_fragments/mso.py b/lib/ansible/plugins/doc_fragments/mso.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/mso.py rename to lib/ansible/plugins/doc_fragments/mso.py diff --git a/lib/ansible/utils/module_docs_fragments/mysql.py b/lib/ansible/plugins/doc_fragments/mysql.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/mysql.py rename to lib/ansible/plugins/doc_fragments/mysql.py diff --git a/lib/ansible/utils/module_docs_fragments/netapp.py b/lib/ansible/plugins/doc_fragments/netapp.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/netapp.py rename to lib/ansible/plugins/doc_fragments/netapp.py diff --git a/lib/ansible/utils/module_docs_fragments/netconf.py b/lib/ansible/plugins/doc_fragments/netconf.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/netconf.py rename to lib/ansible/plugins/doc_fragments/netconf.py diff --git a/lib/ansible/utils/module_docs_fragments/netscaler.py b/lib/ansible/plugins/doc_fragments/netscaler.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/netscaler.py rename to lib/ansible/plugins/doc_fragments/netscaler.py diff --git a/lib/ansible/utils/module_docs_fragments/nios.py b/lib/ansible/plugins/doc_fragments/nios.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/nios.py rename to lib/ansible/plugins/doc_fragments/nios.py diff --git a/lib/ansible/utils/module_docs_fragments/nso.py b/lib/ansible/plugins/doc_fragments/nso.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/nso.py rename to lib/ansible/plugins/doc_fragments/nso.py diff --git a/lib/ansible/utils/module_docs_fragments/nxos.py b/lib/ansible/plugins/doc_fragments/nxos.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/nxos.py rename to lib/ansible/plugins/doc_fragments/nxos.py diff --git a/lib/ansible/utils/module_docs_fragments/oneview.py b/lib/ansible/plugins/doc_fragments/oneview.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/oneview.py rename to lib/ansible/plugins/doc_fragments/oneview.py diff --git a/lib/ansible/utils/module_docs_fragments/online.py b/lib/ansible/plugins/doc_fragments/online.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/online.py rename to lib/ansible/plugins/doc_fragments/online.py diff --git a/lib/ansible/utils/module_docs_fragments/onyx.py b/lib/ansible/plugins/doc_fragments/onyx.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/onyx.py rename to lib/ansible/plugins/doc_fragments/onyx.py diff --git a/lib/ansible/utils/module_docs_fragments/opennebula.py b/lib/ansible/plugins/doc_fragments/opennebula.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/opennebula.py rename to lib/ansible/plugins/doc_fragments/opennebula.py diff --git a/lib/ansible/utils/module_docs_fragments/openstack.py b/lib/ansible/plugins/doc_fragments/openstack.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/openstack.py rename to lib/ansible/plugins/doc_fragments/openstack.py diff --git a/lib/ansible/utils/module_docs_fragments/openswitch.py b/lib/ansible/plugins/doc_fragments/openswitch.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/openswitch.py rename to lib/ansible/plugins/doc_fragments/openswitch.py diff --git a/lib/ansible/utils/module_docs_fragments/ovirt.py b/lib/ansible/plugins/doc_fragments/ovirt.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/ovirt.py rename to lib/ansible/plugins/doc_fragments/ovirt.py diff --git a/lib/ansible/utils/module_docs_fragments/ovirt_facts.py b/lib/ansible/plugins/doc_fragments/ovirt_facts.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/ovirt_facts.py rename to lib/ansible/plugins/doc_fragments/ovirt_facts.py diff --git a/lib/ansible/utils/module_docs_fragments/panos.py b/lib/ansible/plugins/doc_fragments/panos.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/panos.py rename to lib/ansible/plugins/doc_fragments/panos.py diff --git a/lib/ansible/utils/module_docs_fragments/postgres.py b/lib/ansible/plugins/doc_fragments/postgres.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/postgres.py rename to lib/ansible/plugins/doc_fragments/postgres.py diff --git a/lib/ansible/utils/module_docs_fragments/proxysql.py b/lib/ansible/plugins/doc_fragments/proxysql.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/proxysql.py rename to lib/ansible/plugins/doc_fragments/proxysql.py diff --git a/lib/ansible/utils/module_docs_fragments/purestorage.py b/lib/ansible/plugins/doc_fragments/purestorage.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/purestorage.py rename to lib/ansible/plugins/doc_fragments/purestorage.py diff --git a/lib/ansible/utils/module_docs_fragments/rabbitmq.py b/lib/ansible/plugins/doc_fragments/rabbitmq.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/rabbitmq.py rename to lib/ansible/plugins/doc_fragments/rabbitmq.py diff --git a/lib/ansible/utils/module_docs_fragments/rackspace.py b/lib/ansible/plugins/doc_fragments/rackspace.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/rackspace.py rename to lib/ansible/plugins/doc_fragments/rackspace.py diff --git a/lib/ansible/utils/module_docs_fragments/return_common.py b/lib/ansible/plugins/doc_fragments/return_common.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/return_common.py rename to lib/ansible/plugins/doc_fragments/return_common.py diff --git a/lib/ansible/utils/module_docs_fragments/scaleway.py b/lib/ansible/plugins/doc_fragments/scaleway.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/scaleway.py rename to lib/ansible/plugins/doc_fragments/scaleway.py diff --git a/lib/ansible/utils/module_docs_fragments/shell_common.py b/lib/ansible/plugins/doc_fragments/shell_common.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/shell_common.py rename to lib/ansible/plugins/doc_fragments/shell_common.py diff --git a/lib/ansible/utils/module_docs_fragments/sros.py b/lib/ansible/plugins/doc_fragments/sros.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/sros.py rename to lib/ansible/plugins/doc_fragments/sros.py diff --git a/lib/ansible/utils/module_docs_fragments/tower.py b/lib/ansible/plugins/doc_fragments/tower.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/tower.py rename to lib/ansible/plugins/doc_fragments/tower.py diff --git a/lib/ansible/utils/module_docs_fragments/ucs.py b/lib/ansible/plugins/doc_fragments/ucs.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/ucs.py rename to lib/ansible/plugins/doc_fragments/ucs.py diff --git a/lib/ansible/utils/module_docs_fragments/url.py b/lib/ansible/plugins/doc_fragments/url.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/url.py rename to lib/ansible/plugins/doc_fragments/url.py diff --git a/lib/ansible/utils/module_docs_fragments/utm.py b/lib/ansible/plugins/doc_fragments/utm.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/utm.py rename to lib/ansible/plugins/doc_fragments/utm.py diff --git a/lib/ansible/utils/module_docs_fragments/validate.py b/lib/ansible/plugins/doc_fragments/validate.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/validate.py rename to lib/ansible/plugins/doc_fragments/validate.py diff --git a/lib/ansible/utils/module_docs_fragments/vca.py b/lib/ansible/plugins/doc_fragments/vca.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/vca.py rename to lib/ansible/plugins/doc_fragments/vca.py diff --git a/lib/ansible/utils/module_docs_fragments/vmware.py b/lib/ansible/plugins/doc_fragments/vmware.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/vmware.py rename to lib/ansible/plugins/doc_fragments/vmware.py diff --git a/lib/ansible/utils/module_docs_fragments/vmware_rest_client.py b/lib/ansible/plugins/doc_fragments/vmware_rest_client.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/vmware_rest_client.py rename to lib/ansible/plugins/doc_fragments/vmware_rest_client.py diff --git a/lib/ansible/utils/module_docs_fragments/vultr.py b/lib/ansible/plugins/doc_fragments/vultr.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/vultr.py rename to lib/ansible/plugins/doc_fragments/vultr.py diff --git a/lib/ansible/utils/module_docs_fragments/vyos.py b/lib/ansible/plugins/doc_fragments/vyos.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/vyos.py rename to lib/ansible/plugins/doc_fragments/vyos.py diff --git a/lib/ansible/utils/module_docs_fragments/xenserver.py b/lib/ansible/plugins/doc_fragments/xenserver.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/xenserver.py rename to lib/ansible/plugins/doc_fragments/xenserver.py diff --git a/lib/ansible/utils/module_docs_fragments/zabbix.py b/lib/ansible/plugins/doc_fragments/zabbix.py similarity index 100% rename from lib/ansible/utils/module_docs_fragments/zabbix.py rename to lib/ansible/plugins/doc_fragments/zabbix.py diff --git a/lib/ansible/plugins/loader.py b/lib/ansible/plugins/loader.py index c6c32c8e5d..7e1236318a 100644 --- a/lib/ansible/plugins/loader.py +++ b/lib/ansible/plugins/loader.py @@ -633,12 +633,11 @@ _PLUGIN_FILTERS = _load_plugin_filter() # doc fragments first fragment_loader = PluginLoader( 'ModuleDocFragment', - 'ansible.utils.module_docs_fragments', - os.path.join(os.path.dirname(__file__), 'module_docs_fragments'), - '', + 'ansible.plugins.doc_fragments', + C.DOC_FRAGMENT_PLUGIN_PATH, + 'doc_fragments', ) - action_loader = PluginLoader( 'ActionModule', 'ansible.plugins.action', diff --git a/lib/ansible/utils/plugin_docs.py b/lib/ansible/utils/plugin_docs.py index 6cbc50859d..1735a6c271 100644 --- a/lib/ansible/utils/plugin_docs.py +++ b/lib/ansible/utils/plugin_docs.py @@ -97,7 +97,7 @@ def add_fragments(doc, filename, fragment_loader): def get_docstring(filename, fragment_loader, verbose=False, ignore_errors=False): """ - DOCUMENTATION can be extended using documentation fragments loaded by the PluginLoader from the module_docs_fragments directory. + DOCUMENTATION can be extended using documentation fragments loaded by the PluginLoader from the doc_fragments plugins. """ data = read_docstring(filename, verbose=verbose, ignore_errors=ignore_errors) diff --git a/test/runner/lib/classification.py b/test/runner/lib/classification.py index 160a797b21..f80e1c6e52 100644 --- a/test/runner/lib/classification.py +++ b/test/runner/lib/classification.py @@ -559,7 +559,7 @@ class PathMapper(object): 'units': 'all', } - if path.startswith('lib/ansible/utils/module_docs_fragments/'): + if path.startswith('lib/ansible/plugins/docs_fragments/'): return { 'sanity': 'all', } diff --git a/test/runner/lib/sanity/ansible_doc.py b/test/runner/lib/sanity/ansible_doc.py index a3b35d93e6..d94d24ae60 100644 --- a/test/runner/lib/sanity/ansible_doc.py +++ b/test/runner/lib/sanity/ansible_doc.py @@ -41,9 +41,11 @@ class AnsibleDocTest(SanityMultipleVersion): skip_file = 'test/sanity/ansible-doc/skip.txt' skip_modules = set(read_lines_without_comments(skip_file, remove_blank_lines=True)) + # This should use documentable plugins from constants instead plugin_type_blacklist = set([ # not supported by ansible-doc 'action', + 'doc_fragments', 'cliconf', 'filter', 'httpapi', diff --git a/test/runner/lib/sanity/yamllint.py b/test/runner/lib/sanity/yamllint.py index 1073fb26eb..10c5b09c3d 100644 --- a/test/runner/lib/sanity/yamllint.py +++ b/test/runner/lib/sanity/yamllint.py @@ -44,7 +44,7 @@ class YamllintTest(SanitySingleVersion): [i.path for i in targets.include if os.path.splitext(i.path)[1] == '.py' and os.path.basename(i.path) != '__init__.py' and - i.path.startswith('lib/ansible/utils/module_docs_fragments/')], + i.path.startswith('lib/ansible/plugins/docs_fragments/')], ] paths = [sorted(p) for p in paths if p] diff --git a/test/sanity/code-smell/boilerplate.py b/test/sanity/code-smell/boilerplate.py index 6cd9665b11..867e37b4d1 100755 --- a/test/sanity/code-smell/boilerplate.py +++ b/test/sanity/code-smell/boilerplate.py @@ -30,7 +30,7 @@ def main(): 'lib/ansible/modules/network/panos/', 'lib/ansible/modules/network/vyos/', 'lib/ansible/modules/windows/', - 'lib/ansible/utils/module_docs_fragments/', + 'lib/ansible/plugins/doc_fragments/', 'test/' ] diff --git a/test/sanity/yamllint/yamllinter.py b/test/sanity/yamllint/yamllinter.py index d8926e2238..5b0c1b8fa9 100755 --- a/test/sanity/yamllint/yamllinter.py +++ b/test/sanity/yamllint/yamllinter.py @@ -147,7 +147,7 @@ class YamlChecker(object): for body_statement in module_ast.body: if isinstance(body_statement, ast.Assign): check_assignment(body_statement, module_doc_types) - elif path.startswith('lib/ansible/utils/module_docs_fragments/'): + elif path.startswith('lib/ansible/plugins/docs_fragments/'): for body_statement in module_ast.body: if isinstance(body_statement, ast.ClassDef): for class_statement in body_statement.body: