diff --git a/.github/workflows/docs-pr.yml b/.github/workflows/docs-pr.yml index 4b3f1f3..14a917a 100644 --- a/.github/workflows/docs-pr.yml +++ b/.github/workflows/docs-pr.yml @@ -32,6 +32,8 @@ jobs: init-extra-html-theme-options: | documentation_home_url=https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/branch/main/ render-file-line: '> * `$` [$](https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/pr/${{ github.event.number }}/$)' + provide-link-targets: | + ansible_collections.ansible.netcommon.network_cli_connection__parameter-ssh_type publish-docs-gh-pages: # for now we won't run this on forks diff --git a/changelogs/fragments/semantic-markup.yml b/changelogs/fragments/semantic-markup.yml new file mode 100644 index 0000000..e8a448f --- /dev/null +++ b/changelogs/fragments/semantic-markup.yml @@ -0,0 +1,5 @@ +known_issues: + - Ansible markup will show up in raw form on ansible-doc text output for ansible-core + before 2.15. If you have trouble deciphering the documentation markup, please + upgrade to ansible-core 2.15 (or newer), or read the HTML documentation on + https://docs.ansible.com/ansible/devel/collections/community/routeros/. diff --git a/docs/docsite/rst/api-guide.rst b/docs/docsite/rst/api-guide.rst index f3bb629..a672060 100644 --- a/docs/docsite/rst/api-guide.rst +++ b/docs/docsite/rst/api-guide.rst @@ -105,11 +105,11 @@ Here all three tasks will use the options set for the module defaults group. Setting up encryption --------------------- -It is recommended to always use ``tls: true`` when connecting with the API, even if you are only connecting to the device through a trusted network. The following options control how TLS/SSL is used: +It is recommended to always use :ansopt:`tls=true` when connecting with the API, even if you are only connecting to the device through a trusted network. The following options control how TLS/SSL is used: -:force_no_cert: Setting to ``true`` connects to the device without a certificate. **This is discouraged to use in production and is susceptible to Man-in-the-Middle attacks**, but might be useful when setting the device up. The default value is ``false``. -:validate_certs: Setting to ``false`` disables any certificate validation. **This is discouraged to use in production**, but is needed when setting the device up. The default value is ``true``. -:validate_cert_hostname: Setting to ``false`` (default) disables hostname verification during certificate validation. This is needed if the hostnames specified in the certificate do not match the hostname used for connecting (usually the device's IP). It is recommended to set up the certificate correctly and set this to ``true``; the default ``false`` is chosen for backwards compatibility to an older version of the module. +:force_no_cert: Setting to :ansval:`true` connects to the device without a certificate. **This is discouraged to use in production and is susceptible to Man-in-the-Middle attacks**, but might be useful when setting the device up. The default value is :ansval:`false`. +:validate_certs: Setting to :ansval:`false` disables any certificate validation. **This is discouraged to use in production**, but is needed when setting the device up. The default value is :ansval:`true`. +:validate_cert_hostname: Setting to :ansval:`false` (default) disables hostname verification during certificate validation. This is needed if the hostnames specified in the certificate do not match the hostname used for connecting (usually the device's IP). It is recommended to set up the certificate correctly and set this to :ansval:`true`; the default :ansval:`false` is chosen for backwards compatibility to an older version of the module. :ca_path: If you are not using a commerically trusted CA certificate to sign your device's certificate, or have not included your CA certificate in Python's truststore, you need to point this option to the CA certificate. We recommend to create a CA certificate that is used to sign the certificates for your RouterOS devices, and have the certificates include the correct hostname(s), including the IP of the device. That way, you can fully enable TLS and be sure that you always talk to the correct device. diff --git a/docs/docsite/rst/quoting.rst b/docs/docsite/rst/quoting.rst index 3091fc8..1356f7b 100644 --- a/docs/docsite/rst/quoting.rst +++ b/docs/docsite/rst/quoting.rst @@ -16,4 +16,4 @@ The community.routeros collection provides a set of Jinja2 filter plugins which - The :ref:`community.routeros.quote_argument filter ` quotes an argument with or without a value: ``'comment=this is a "comment"' | community.routeros.quote_argument == 'comment="this is a \\"comment\\""'``. - The :ref:`community.routeros.join filter ` quotes a list of arguments and joins them to one string: ``['foo=bar', 'comment=foo is bar'] | community.routeros.join == 'foo=bar comment="foo is bar"'``. - The :ref:`community.routeros.split filter ` splits a command into a list of arguments (with or without values): ``'foo=bar comment="foo is bar"' | community.routeros.split == ['foo=bar', 'comment=foo is bar']`` -- The :ref:`community.routeros.list_to_dict filter ` splits a list of arguments with values into a dictionary: ``['foo=bar', 'comment=foo is bar'] | community.routeros.list_to_dict == {'foo': 'bar', 'comment': 'foo is bar'}``. It has two optional arguments: ``require_assignment`` (default value ``true``) allows to accept arguments without values when set to ``false``; and ``skip_empty_values`` (default value ``false``) allows to skip arguments whose value is empty. +- The :ref:`community.routeros.list_to_dict filter ` splits a list of arguments with values into a dictionary: ``['foo=bar', 'comment=foo is bar'] | community.routeros.list_to_dict == {'foo': 'bar', 'comment': 'foo is bar'}``. It has two optional arguments: :ansopt:`community.routeros.list_to_dict#filter:require_assignment` (default value :ansval:`true`) allows to accept arguments without values when set to :ansval:`false`; and :ansopt:`community.routeros.list_to_dict#filter:skip_empty_values` (default value :ansval:`false`) allows to skip arguments whose value is empty. diff --git a/docs/docsite/rst/ssh-guide.rst b/docs/docsite/rst/ssh-guide.rst index bdbdbfe..17254c5 100644 --- a/docs/docsite/rst/ssh-guide.rst +++ b/docs/docsite/rst/ssh-guide.rst @@ -31,7 +31,7 @@ Important notes 3. When using the :ref:`community.routeros.command module ` module, make sure to not specify too long commands. Alternatively, add something like ``+cet512w`` to the username (replace ``admin`` with ``admin+cet512w``) to tell RouterOS to not wrap before 512 characters in a line (`see issue for details `__). -4. Finally, the :ref:`ansible.netcommon.network_cli connection plugin ` uses `paramiko `_ by default to connect to devices with SSH. You can set its ``ssh_type`` option to ``libssh`` to use `ansible-pylibssh `_ instead, which offers Python bindings to libssh. See its documentation for details. +4. Finally, the :ref:`ansible.netcommon.network_cli connection plugin ` uses `paramiko `_ by default to connect to devices with SSH. You can set its :ansopt:`ansible.netcommon.network_cli#connection:ssh_type`` option to :ansval:`libssh` to use `ansible-pylibssh `_ instead, which offers Python bindings to libssh. See its documentation for details. Setting up an inventory ----------------------- diff --git a/plugins/doc_fragments/api.py b/plugins/doc_fragments/api.py index dea374b..7f77e8f 100644 --- a/plugins/doc_fragments/api.py +++ b/plugins/doc_fragments/api.py @@ -43,48 +43,48 @@ options: - ssl port: description: - - RouterOS api port. If I(tls) is set, port will apply to TLS/SSL connection. - - Defaults are C(8728) for the HTTP API, and C(8729) for the HTTPS API. + - RouterOS api port. If O(tls) is set, port will apply to TLS/SSL connection. + - Defaults are V(8728) for the HTTP API, and V(8729) for the HTTPS API. type: int force_no_cert: description: - - Set to C(true) to connect without a certificate when I(tls=true). - - See also I(validate_certs). + - Set to V(true) to connect without a certificate when O(tls=true). + - See also O(validate_certs). - B(Note:) this forces the use of anonymous Diffie-Hellman (ADH) ciphers. The protocol is susceptible to Man-in-the-Middle attacks, because the keys used in the exchange are not authenticated. Instead of simply connecting without a certificate to "make things work" have a look at - I(validate_certs) and I(ca_path). + O(validate_certs) and O(ca_path). type: bool default: false version_added: 2.4.0 validate_certs: description: - - Set to C(false) to skip validation of TLS certificates. - - See also I(validate_cert_hostname). Only used when I(tls=true). + - Set to V(false) to skip validation of TLS certificates. + - See also O(validate_cert_hostname). Only used when O(tls=true). - B(Note:) instead of simply deactivating certificate validations to "make things work", please consider creating your own CA certificate and using it to sign certificates used - for your router. You can tell the module about your CA certificate with the I(ca_path) + for your router. You can tell the module about your CA certificate with the O(ca_path) option. type: bool default: true version_added: 1.2.0 validate_cert_hostname: description: - - Set to C(true) to validate hostnames in certificates. - - See also I(validate_certs). Only used when I(tls=true) and I(validate_certs=true). + - Set to V(true) to validate hostnames in certificates. + - See also O(validate_certs). Only used when O(tls=true) and O(validate_certs=true). type: bool default: false version_added: 1.2.0 ca_path: description: - PEM formatted file that contains a CA certificate to be used for certificate validation. - - See also I(validate_cert_hostname). Only used when I(tls=true) and I(validate_certs=true). + - See also O(validate_cert_hostname). Only used when O(tls=true) and O(validate_certs=true). type: path version_added: 1.2.0 encoding: description: - Use the specified encoding when communicating with the RouterOS device. - - Default is C(ASCII). Note that C(UTF-8) requires librouteros 3.2.1 or newer. + - Default is V(ASCII). Note that V(UTF-8) requires librouteros 3.2.1 or newer. type: str default: ASCII version_added: 2.1.0 diff --git a/plugins/filter/list_to_dict.yml b/plugins/filter/list_to_dict.yml index 920414c..6e7992d 100644 --- a/plugins/filter/list_to_dict.yml +++ b/plugins/filter/list_to_dict.yml @@ -12,18 +12,18 @@ DOCUMENTATION: options: _input: description: - - A list of assignments. Can be the result of the C(community.routeros.split) filter. + - A list of assignments. Can be the result of the P(community.routeros.split#filter) filter. type: list elements: string required: true require_assignment: description: - - Allows to accept arguments without values when set to C(false). + - Allows to accept arguments without values when set to V(false). type: boolean default: true skip_empty_values: description: - - Allows to skip arguments whose value is empty when set to C(true). + - Allows to skip arguments whose value is empty when set to V(true). type: boolean default: false author: diff --git a/plugins/modules/api.py b/plugins/modules/api.py index f9c619f..65b9796 100644 --- a/plugins/modules/api.py +++ b/plugins/modules/api.py @@ -17,7 +17,7 @@ description: - Ansible module for RouterOS API with the Python C(librouteros) library. - This module can add, remove, update, query and execute arbitrary command in RouterOS via API. notes: - - I(add), I(remove), I(update), I(cmd) and I(query) are mutually exclusive. + - O(add), O(remove), O(update), O(cmd), and O(query) are mutually exclusive. - Use the M(community.routeros.api_modify) and M(community.routeros.api_find_and_modify) modules for more specific modifications, and the M(community.routeros.api_info) module for a more controlled way of returning all entries for a path. @@ -40,26 +40,26 @@ options: description: - Main path for all other arguments. - If other arguments are not set, api will return all items in selected path. - - Example C(ip address). Equivalent of RouterOS CLI C(/ip address print). + - Example V(ip address). Equivalent of RouterOS CLI C(/ip address print). required: true type: str add: description: - Will add selected arguments in selected path to RouterOS config. - - Example C(address=1.1.1.1/32 interface=ether1). + - Example V(address=1.1.1.1/32 interface=ether1). - Equivalent in RouterOS CLI C(/ip address add address=1.1.1.1/32 interface=ether1). type: str remove: description: - Remove config/value from RouterOS by '.id'. - - Example C(*03) will remove config/value with C(id=*03) in selected path. + - Example V(*03) will remove config/value with C(id=*03) in selected path. - Equivalent in RouterOS CLI C(/ip address remove numbers=1). - Note C(number) in RouterOS CLI is different from C(.id). type: str update: description: - Update config/value in RouterOS by '.id' in selected path. - - Example C(.id=*03 address=1.1.1.3/32) and path C(ip address) will replace existing ip address with C(.id=*03). + - Example V(.id=*03 address=1.1.1.3/32) and path V(ip address) will replace existing ip address with C(.id=*03). - Equivalent in RouterOS CLI C(/ip address set address=1.1.1.3/32 numbers=1). - Note C(number) in RouterOS CLI is different from C(.id). type: str @@ -67,11 +67,11 @@ options: description: - Query given path for selected query attributes from RouterOS aip. - WHERE is key word which extend query. WHERE format is key operator value - with spaces. - - WHERE valid operators are C(==) or C(eq), C(!=) or C(not), C(>) or C(more), C(<) or C(less). - - Example path C(ip address) and query C(.id address) will return only C(.id) and C(address) for all items in C(ip address) path. - - Example path C(ip address) and query C(.id address WHERE address == 1.1.1.3/32). - will return only C(.id) and C(address) for items in C(ip address) path, where address is eq to 1.1.1.3/32. - - Example path C(interface) and query C(mtu name WHERE mut > 1400) will + - WHERE valid operators are V(==) or V(eq), V(!=) or V(not), V(>) or V(more), V(<) or V(less). + - Example path V(ip address) and query V(.id address) will return only C(.id) and C(address) for all items in V(ip address) path. + - Example path V(ip address) and query V(.id address WHERE address == 1.1.1.3/32). + will return only C(.id) and C(address) for items in V(ip address) path, where address is eq to 1.1.1.3/32. + - Example path V(interface) and query V(mtu name WHERE mut > 1400) will return only interfaces C(mtu,name) where mtu is bigger than 1400. - Equivalent in RouterOS CLI C(/interface print where mtu > 1400). type: str @@ -84,65 +84,69 @@ options: attributes: description: - The list of attributes to return. - - Every attribute used in a I(where) clause need to be listed here. + - Every attribute used in a O(extended_query.where[]) clause need to be listed here. type: list elements: str required: true where: description: - Allows to restrict the objects returned. - - The conditions here must all match. An I(or) condition needs at least one of its conditions to match. + - The conditions here must all match. An O(extended_query.where[].or) condition needs at least one of its conditions to match. type: list elements: dict suboptions: attribute: description: - - The attribute to match. Must be part of I(attributes). - - Either I(or) or all of I(attribute), I(is), and I(value) have to be specified. + - The attribute to match. Must be part of O(extended_query.attributes). + - Either O(extended_query.where[].or) or all of O(extended_query.where[].attribute), O(extended_query.where[].is), + and O(extended_query.where[].value) have to be specified. type: str is: description: - The operator to use for matching. - - For equality use C(==) or C(eq). For less use C(<) or C(less). For more use C(>) or C(more). - - Use C(in) to check whether the value is part of a list. In that case, I(value) must be a list. - - Either I(or) or all of I(attribute), I(is), and I(value) have to be specified. + - For equality use V(==) or V(eq). For less use V(<) or V(less). For more use V(>) or V(more). + - Use V(in) to check whether the value is part of a list. In that case, O(extended_query.where[].value) must be a list. + - Either O(extended_query.where[].or) or all of O(extended_query.where[].attribute), O(extended_query.where[].is), + and O(extended_query.where[].value) have to be specified. type: str choices: ["==", "!=", ">", "<", "in", "eq", "not", "more", "less"] value: description: - - The value to compare to. Must be a list for I(is=in). - - Either I(or) or all of I(attribute), I(is), and I(value) have to be specified. + - The value to compare to. Must be a list for O(extended_query.where[].is=in). + - Either O(extended_query.where[].or) or all of O(extended_query.where[].attribute), O(extended_query.where[].is), + and O(extended_query.where[].value) have to be specified. type: raw or: description: - A list of conditions so that at least one of them has to match. - - Either I(or) or all of I(attribute), I(is), and I(value) have to be specified. + - Either O(extended_query.where[].or) or all of O(extended_query.where[].attribute), O(extended_query.where[].is), + and O(extended_query.where[].value) have to be specified. type: list elements: dict suboptions: attribute: description: - - The attribute to match. Must be part of I(attributes). + - The attribute to match. Must be part of O(extended_query.attributes). type: str required: true is: description: - The operator to use for matching. - - For equality use C(==) or C(eq). For less use C(<) or C(less). For more use C(>) or C(more). - - Use C(in) to check whether the value is part of a list. In that case, I(value) must be a list. + - For equality use V(==) or V(eq). For less use V(<) or V(less). For more use V(>) or V(more). + - Use V(in) to check whether the value is part of a list. In that case, O(extended_query.where[].or[].value) must be a list. type: str choices: ["==", "!=", ">", "<", "in", "eq", "not", "more", "less"] required: true value: description: - - The value to compare to. Must be a list for I(is=in). + - The value to compare to. Must be a list for O(extended_query.where[].or[].is=in). type: raw required: true cmd: description: - Execute any/arbitrary command in selected path, after the command we can add C(.id). - - Example path C(system script) and cmd C(run .id=*03) is equivalent in RouterOS CLI C(/system script run number=0). - - Example path C(ip address) and cmd C(print) is equivalent in RouterOS CLI C(/ip address print). + - Example path V(system script) and cmd V(run .id=*03) is equivalent in RouterOS CLI C(/system script run number=0). + - Example path V(ip address) and cmd V(print) is equivalent in RouterOS CLI C(/ip address print). type: str seealso: - ref: ansible_collections.community.routeros.docsite.quoting diff --git a/plugins/modules/api_facts.py b/plugins/modules/api_facts.py index f297236..296621e 100644 --- a/plugins/modules/api_facts.py +++ b/plugins/modules/api_facts.py @@ -41,9 +41,9 @@ options: description: - When supplied, this argument will restrict the facts collected to a given subset. Possible values for this argument include - C(all), C(hardware), C(interfaces), and C(routing). + V(all), V(hardware), V(interfaces), and V(routing). - Can specify a list of values to include a larger subset. - Values can also be used with an initial C(!) to specify that a + Values can also be used with an initial V(!) to specify that a specific subset should not be collected. required: false default: @@ -89,93 +89,93 @@ ansible_facts: # default ansible_net_model: description: The model name returned from the device. - returned: I(gather_subset) contains C(default) + returned: O(gather_subset) contains V(default) type: str ansible_net_serialnum: description: The serial number of the remote device. - returned: I(gather_subset) contains C(default) + returned: O(gather_subset) contains V(default) type: str ansible_net_version: description: The operating system version running on the remote device. - returned: I(gather_subset) contains C(default) + returned: O(gather_subset) contains V(default) type: str ansible_net_hostname: description: The configured hostname of the device. - returned: I(gather_subset) contains C(default) + returned: O(gather_subset) contains V(default) type: str ansible_net_arch: description: The CPU architecture of the device. - returned: I(gather_subset) contains C(default) + returned: O(gather_subset) contains V(default) type: str ansible_net_uptime: description: The uptime of the device. - returned: I(gather_subset) contains C(default) + returned: O(gather_subset) contains V(default) type: str ansible_net_cpu_load: description: Current CPU load. - returned: I(gather_subset) contains C(default) + returned: O(gather_subset) contains V(default) type: str # hardware ansible_net_spacefree_mb: description: The available disk space on the remote device in MiB. - returned: I(gather_subset) contains C(hardware) + returned: O(gather_subset) contains V(hardware) type: dict ansible_net_spacetotal_mb: description: The total disk space on the remote device in MiB. - returned: I(gather_subset) contains C(hardware) + returned: O(gather_subset) contains V(hardware) type: dict ansible_net_memfree_mb: description: The available free memory on the remote device in MiB. - returned: I(gather_subset) contains C(hardware) + returned: O(gather_subset) contains V(hardware) type: int ansible_net_memtotal_mb: description: The total memory on the remote device in MiB. - returned: I(gather_subset) contains C(hardware) + returned: O(gather_subset) contains V(hardware) type: int # interfaces ansible_net_all_ipv4_addresses: description: All IPv4 addresses configured on the device. - returned: I(gather_subset) contains C(interfaces) + returned: O(gather_subset) contains V(interfaces) type: list ansible_net_all_ipv6_addresses: description: All IPv6 addresses configured on the device. - returned: I(gather_subset) contains C(interfaces) + returned: O(gather_subset) contains V(interfaces) type: list ansible_net_interfaces: description: A hash of all interfaces running on the system. - returned: I(gather_subset) contains C(interfaces) + returned: O(gather_subset) contains V(interfaces) type: dict ansible_net_neighbors: description: The list of neighbors from the remote device. - returned: I(gather_subset) contains C(interfaces) + returned: O(gather_subset) contains V(interfaces) type: dict # routing ansible_net_bgp_peer: description: A dictionary with BGP peer information. - returned: I(gather_subset) contains C(routing) + returned: O(gather_subset) contains V(routing) type: dict ansible_net_bgp_vpnv4_route: description: A dictionary with BGP vpnv4 route information. - returned: I(gather_subset) contains C(routing) + returned: O(gather_subset) contains V(routing) type: dict ansible_net_bgp_instance: description: A dictionary with BGP instance information. - returned: I(gather_subset) contains C(routing) + returned: O(gather_subset) contains V(routing) type: dict ansible_net_route: description: A dictionary for routes in all routing tables. - returned: I(gather_subset) contains C(routing) + returned: O(gather_subset) contains V(routing) type: dict ansible_net_ospf_instance: description: A dictionary with OSPF instances. - returned: I(gather_subset) contains C(routing) + returned: O(gather_subset) contains V(routing) type: dict ansible_net_ospf_neighbor: description: A dictionary with OSPF neighbors. - returned: I(gather_subset) contains C(routing) + returned: O(gather_subset) contains V(routing) type: dict """ diff --git a/plugins/modules/api_find_and_modify.py b/plugins/modules/api_find_and_modify.py index 0be3f70..176c943 100644 --- a/plugins/modules/api_find_and_modify.py +++ b/plugins/modules/api_find_and_modify.py @@ -21,7 +21,7 @@ description: or change multiple entries in different ways in one step. notes: - "If you want to change values based on their old values (like change all comments 'foo' to 'bar') and make sure that - there are at least N such values, you can use I(require_matches_min=N) together with I(allow_no_matches=true). + there are at least N such values, you can use O(require_matches_min=N) together with O(allow_no_matches=true). This will make the module fail if there are less than N such entries, but not if there is no match. The latter case is needed for idempotency of the task: once the values have been changed, there should be no further match." extends_documentation_fragment: @@ -40,21 +40,21 @@ options: path: description: - Path to query. - - An example value is C(ip address). This is equivalent to running C(/ip address) in the RouterOS CLI. + - An example value is V(ip address). This is equivalent to running C(/ip address) in the RouterOS CLI. required: true type: str find: description: - Fields to search for. - - The module will only consider entries in the given I(path) that match all fields provided here. - - Use YAML C(~), or prepend keys with C(!), to specify an unset value. + - The module will only consider entries in the given O(path) that match all fields provided here. + - Use YAML V(~), or prepend keys with V(!), to specify an unset value. - Note that if the dictionary specified here is empty, every entry in the path will be matched. required: true type: dict values: description: - - On all entries matching the conditions in I(find), set the keys of this option to the values specified here. - - Use YAML C(~), or prepend keys with C(!), to specify to unset a value. + - On all entries matching the conditions in O(find), set the keys of this option to the values specified here. + - Use YAML V(~), or prepend keys with V(!), to specify to unset a value. required: true type: dict require_matches_min: @@ -72,7 +72,7 @@ options: allow_no_matches: description: - Whether to allow that no match is found. - - If not specified, this value is induced from whether I(require_matches_min) is 0 or larger. + - If not specified, this value is induced from whether O(require_matches_min) is 0 or larger. type: bool seealso: - module: community.routeros.api @@ -146,7 +146,7 @@ new_data: returned: success match_count: description: - - The number of entries that matched the criteria in I(find). + - The number of entries that matched the criteria in O(find). sample: 1 type: int returned: success diff --git a/plugins/modules/api_info.py b/plugins/modules/api_info.py index 50228c0..4fda150 100644 --- a/plugins/modules/api_info.py +++ b/plugins/modules/api_info.py @@ -18,9 +18,9 @@ version_added: 2.2.0 description: - Allows to retrieve information for a path using the API. - This can be used to backup a path to restore it with the M(community.routeros.api_modify) module. - - Entries are normalized, dynamic and builtin entries are not returned. Use the I(handle_disabled) and - I(hide_defaults) options to control normalization, the I(include_dynamic) and I(include_builtin) options to also return - dynamic resp. builtin entries, and use I(unfiltered) to return all fields including counters. + - Entries are normalized, dynamic and builtin entries are not returned. Use the O(handle_disabled) and + O(hide_defaults) options to control normalization, the O(include_dynamic) and O(include_builtin) options to also return + dynamic resp. builtin entries, and use O(unfiltered) to return all fields including counters. - B(Note) that this module is still heavily in development, and only supports B(some) paths. If you want to support new paths, or think you found problems with existing paths, please first L(create an issue in the community.routeros Issue Tracker,https://github.com/ansible-collections/community.routeros/issues/). @@ -37,7 +37,7 @@ options: path: description: - Path to query. - - An example value is C(ip address). This is equivalent to running C(/ip address print) in the RouterOS CLI. + - An example value is V(ip address). This is equivalent to running C(/ip address print) in the RouterOS CLI. required: true type: str choices: @@ -194,9 +194,9 @@ options: handle_disabled: description: - How to handle unset values. - - C(exclamation) prepends the keys with C(!) in the output with value C(null). - - C(null-value) uses the regular key with value C(null). - - C(omit) omits these values from the result. + - V(exclamation) prepends the keys with V(!) in the output with value V(null). + - V(null-value) uses the regular key with value V(null). + - V(omit) omits these values from the result. type: str choices: - exclamation @@ -212,14 +212,14 @@ options: description: - Whether to include dynamic values. - By default, they are not returned, and the C(dynamic) keys are omitted. - - If set to C(true), they are returned as well, and the C(dynamic) keys are returned as well. + - If set to V(true), they are returned as well, and the C(dynamic) keys are returned as well. type: bool default: false include_builtin: description: - Whether to include builtin values. - By default, they are not returned, and the C(builtin) keys are omitted. - - If set to C(true), they are returned as well, and the C(builtin) keys are returned as well. + - If set to V(true), they are returned as well, and the C(builtin) keys are returned as well. type: bool default: false version_added: 2.4.0 diff --git a/plugins/modules/api_modify.py b/plugins/modules/api_modify.py index 5d410e9..d21d31f 100644 --- a/plugins/modules/api_modify.py +++ b/plugins/modules/api_modify.py @@ -42,7 +42,7 @@ options: path: description: - Path to query. - - An example value is C(ip address). This is equivalent to running modification commands in C(/ip address) in the RouterOS CLI. + - An example value is V(ip address). This is equivalent to running modification commands in C(/ip address) in the RouterOS CLI. required: true type: str choices: @@ -200,15 +200,15 @@ options: elements: dict ensure_order: description: - - Whether to ensure the same order of the config as present in I(data). - - Requires I(handle_absent_entries=remove). + - Whether to ensure the same order of the config as present in O(data). + - Requires O(handle_absent_entries=remove). type: bool default: false handle_absent_entries: description: - - How to handle entries that are present in the current config, but not in I(data). - - C(ignore) ignores them. - - C(remove) removes them. + - How to handle entries that are present in the current config, but not in O(data). + - V(ignore) ignores them. + - V(remove) removes them. type: str choices: - ignore @@ -216,11 +216,11 @@ options: default: ignore handle_entries_content: description: - - For a single entry in I(data), this describes how to handle fields that are not mentioned + - For a single entry in O(data), this describes how to handle fields that are not mentioned in that entry, but appear in the actual config. - - If C(ignore), they are not modified. - - If C(remove), they are removed. If at least one cannot be removed, the module will fail. - - If C(remove_as_much_as_possible), all that can be removed will be removed. The ones that + - If V(ignore), they are not modified. + - If V(remove), they are removed. If at least one cannot be removed, the module will fail. + - If V(remove_as_much_as_possible), all that can be removed will be removed. The ones that cannot be removed will be kept. type: str choices: diff --git a/plugins/modules/command.py b/plugins/modules/command.py index 8442602..52b916b 100644 --- a/plugins/modules/command.py +++ b/plugins/modules/command.py @@ -40,7 +40,7 @@ options: description: - List of commands to send to the remote RouterOS device over the configured provider. The resulting output from the command - is returned. If the I(wait_for) argument is provided, the + is returned. If the O(wait_for) argument is provided, the module is not returned until the condition is satisfied or the number of retries has expired. required: true @@ -57,11 +57,11 @@ options: elements: str match: description: - - The I(match) argument is used in conjunction with the - I(wait_for) argument to specify the match policy. Valid - values are C(all) or C(any). If the value is set to C(all) + - The O(match) argument is used in conjunction with the + O(wait_for) argument to specify the match policy. Valid + values are V(all) or V(any). If the value is set to V(all) then all conditionals in the wait_for must be satisfied. If - the value is set to C(any) then only one of the values must be + the value is set to V(any) then only one of the values must be satisfied. default: all choices: ['any', 'all'] @@ -71,7 +71,7 @@ options: - Specifies the number of retries a command should by tried before it is considered failed. The command is run on the target device every retry and evaluated against the - I(wait_for) conditions. + O(wait_for) conditions. default: 10 type: int interval: diff --git a/plugins/modules/facts.py b/plugins/modules/facts.py index 85c0b37..a47e354 100644 --- a/plugins/modules/facts.py +++ b/plugins/modules/facts.py @@ -31,9 +31,9 @@ options: description: - When supplied, this argument will restrict the facts collected to a given subset. Possible values for this argument include - C(all), C(hardware), C(config), C(interfaces), and C(routing). + V(all), V(hardware), V(config), V(interfaces), and V(routing). - Can specify a list of values to include a larger subset. - Values can also be used with an initial C(!) to specify that a + Values can also be used with an initial V(!) to specify that a specific subset should not be collected. required: false default: @@ -75,55 +75,55 @@ ansible_facts: # default ansible_net_model: description: The model name returned from the device. - returned: I(gather_subset) contains C(default) + returned: O(gather_subset) contains V(default) type: str ansible_net_serialnum: description: The serial number of the remote device. - returned: I(gather_subset) contains C(default) + returned: O(gather_subset) contains V(default) type: str ansible_net_version: description: The operating system version running on the remote device. - returned: I(gather_subset) contains C(default) + returned: O(gather_subset) contains V(default) type: str ansible_net_hostname: description: The configured hostname of the device. - returned: I(gather_subset) contains C(default) + returned: O(gather_subset) contains V(default) type: str ansible_net_arch: description: The CPU architecture of the device. - returned: I(gather_subset) contains C(default) + returned: O(gather_subset) contains V(default) type: str ansible_net_uptime: description: The uptime of the device. - returned: I(gather_subset) contains C(default) + returned: O(gather_subset) contains V(default) type: str ansible_net_cpu_load: description: Current CPU load. - returned: I(gather_subset) contains C(default) + returned: O(gather_subset) contains V(default) type: str # hardware ansible_net_spacefree_mb: description: The available disk space on the remote device in MiB. - returned: I(gather_subset) contains C(hardware) + returned: O(gather_subset) contains V(hardware) type: dict ansible_net_spacetotal_mb: description: The total disk space on the remote device in MiB. - returned: I(gather_subset) contains C(hardware) + returned: O(gather_subset) contains V(hardware) type: dict ansible_net_memfree_mb: description: The available free memory on the remote device in MiB. - returned: I(gather_subset) contains C(hardware) + returned: O(gather_subset) contains V(hardware) type: int ansible_net_memtotal_mb: description: The total memory on the remote device in MiB. - returned: I(gather_subset) contains C(hardware) + returned: O(gather_subset) contains V(hardware) type: int # config ansible_net_config: description: The current active config from the device. - returned: I(gather_subset) contains C(config) + returned: O(gather_subset) contains V(config) type: str ansible_net_config_nonverbose: @@ -132,52 +132,52 @@ ansible_facts: - This value is idempotent in the sense that if the facts module is run twice and the device's config was not changed between the runs, the value is identical. This is achieved by running C(/export) and stripping the timestamp from the comment in the first line. - returned: I(gather_subset) contains C(config) + returned: O(gather_subset) contains V(config) type: str version_added: 1.2.0 # interfaces ansible_net_all_ipv4_addresses: description: All IPv4 addresses configured on the device. - returned: I(gather_subset) contains C(interfaces) + returned: O(gather_subset) contains V(interfaces) type: list ansible_net_all_ipv6_addresses: description: All IPv6 addresses configured on the device. - returned: I(gather_subset) contains C(interfaces) + returned: O(gather_subset) contains V(interfaces) type: list ansible_net_interfaces: description: A hash of all interfaces running on the system. - returned: I(gather_subset) contains C(interfaces) + returned: O(gather_subset) contains V(interfaces) type: dict ansible_net_neighbors: description: The list of neighbors from the remote device. - returned: I(gather_subset) contains C(interfaces) + returned: O(gather_subset) contains V(interfaces) type: dict # routing ansible_net_bgp_peer: description: A dictionary with BGP peer information. - returned: I(gather_subset) contains C(routing) + returned: O(gather_subset) contains V(routing) type: dict ansible_net_bgp_vpnv4_route: description: A dictionary with BGP vpnv4 route information. - returned: I(gather_subset) contains C(routing) + returned: O(gather_subset) contains V(routing) type: dict ansible_net_bgp_instance: description: A dictionary with BGP instance information. - returned: I(gather_subset) contains C(routing) + returned: O(gather_subset) contains V(routing) type: dict ansible_net_route: description: A dictionary for routes in all routing tables. - returned: I(gather_subset) contains C(routing) + returned: O(gather_subset) contains V(routing) type: dict ansible_net_ospf_instance: description: A dictionary with OSPF instances. - returned: I(gather_subset) contains C(routing) + returned: O(gather_subset) contains V(routing) type: dict ansible_net_ospf_neighbor: description: A dictionary with OSPF neighbors. - returned: I(gather_subset) contains C(routing) + returned: O(gather_subset) contains V(routing) type: dict """ import re diff --git a/tests/sanity/extra/extra-docs.py b/tests/sanity/extra/extra-docs.py index c636beb..251e6d7 100755 --- a/tests/sanity/extra/extra-docs.py +++ b/tests/sanity/extra/extra-docs.py @@ -17,7 +17,7 @@ def main(): suffix = ':{env}'.format(env=env["ANSIBLE_COLLECTIONS_PATH"]) if 'ANSIBLE_COLLECTIONS_PATH' in env else '' env['ANSIBLE_COLLECTIONS_PATH'] = '{root}{suffix}'.format(root=os.path.dirname(os.path.dirname(os.path.dirname(os.getcwd()))), suffix=suffix) p = subprocess.run( - ['antsibull-docs', 'lint-collection-docs', '--plugin-docs', '--disallow-semantic-markup', '--skip-rstcheck', '.'], + ['antsibull-docs', 'lint-collection-docs', '--plugin-docs', '--skip-rstcheck', '.'], env=env, check=False, ) diff --git a/tests/sanity/ignore-2.10.txt b/tests/sanity/ignore-2.10.txt index 876765a..ece5b29 100644 --- a/tests/sanity/ignore-2.10.txt +++ b/tests/sanity/ignore-2.10.txt @@ -1,3 +1,6 @@ +docs/docsite/rst/api-guide.rst rstcheck +docs/docsite/rst/quoting.rst rstcheck +docs/docsite/rst/ssh-guide.rst rstcheck update-docs.py compile-2.6 update-docs.py compile-2.7 update-docs.py compile-3.5 diff --git a/tests/sanity/ignore-2.9.txt b/tests/sanity/ignore-2.9.txt index 876765a..ece5b29 100644 --- a/tests/sanity/ignore-2.9.txt +++ b/tests/sanity/ignore-2.9.txt @@ -1,3 +1,6 @@ +docs/docsite/rst/api-guide.rst rstcheck +docs/docsite/rst/quoting.rst rstcheck +docs/docsite/rst/ssh-guide.rst rstcheck update-docs.py compile-2.6 update-docs.py compile-2.7 update-docs.py compile-3.5