Use semantic markup.

Author: felixfontein

docs/docsite/rst/hetzner_guide.rst

@@ -27,7 +27,7 @@ It also provides an inventory plugin:
 Authentication
 --------------
 
-To use Hetzner's API, you need to create an API token. You can manage API tokens in the "API tokens" menu entry in your user menu in the `DNS Console <https://dns.hetzner.com/>`_. You must provide the token to the ``hetzner_token`` option of the modules, its alias ``api_token``, or pass it on in the ``HETZNER_DNS_TOKEN`` environment variable:
+To use Hetzner's API, you need to create an API token. You can manage API tokens in the "API tokens" menu entry in your user menu in the `DNS Console <https://dns.hetzner.com/>`_. You must provide the token to the :ansopt:`hetzner_token` option of the modules, its alias :ansopt:`api_token`, or pass it on in the :envvar:`HETZNER_DNS_TOKEN` environment variable:
 
 .. code-block:: yaml+jinja
 
@@ -96,7 +96,7 @@ The :ref:`community.dns.hetzner_dns_record_set_info module <ansible_collections.
         msg: There is no A record for www.example.com
       when: not result.set
 
-In all examples in this section, you can replace ``zone_name=example.com`` by ``zone_id=aBcDeFgHiJlMnOpQrStUvW`` with the zone's ID string.
+In all examples in this section, you can replace :ansopt:`zone_name=example.com` by :ansopt:`zone_id=aBcDeFgHiJlMnOpQrStUvW` with the zone's ID string.
 
 You can also query a list of all records for a record name or prefix:
 
@@ -157,7 +157,7 @@ The :ref:`community.dns.hetzner_dns_record module <ansible_collections.community
         value: 1.1.1.1
         ttl: 300
 
-To delete records, simply use ``state=absent``. Records will be matched by record name and type, and the TTL will be ignored:
+To delete records, simply use :ansopt:`state=absent`. Records will be matched by record name and type, and the TTL will be ignored:
 
 .. code-block:: yaml+jinja
 
@@ -191,9 +191,9 @@ The :ref:`community.dns.hetzner_dns_record_set module <ansible_collections.commu
           - 1.1.1.1
           - 8.8.8.8
 
-If you want to assert that a record has a certain value, set ``on_existing=keep``. Using ``keep_and_warn`` instead will emit a warning if this happens, and ``keep_and_fail`` will make the module fail.
+If you want to assert that a record has a certain value, set :ansopt:`on_existing=keep`. Using :ansval:`keep_and_warn` instead will emit a warning if this happens, and :ansval:`keep_and_fail` will make the module fail.
 
-To delete values, you can either overwrite the values with value ``[]``, or use ``state=absent``:
+To delete values, you can either overwrite the values with value :ansval:`[]`, or use :ansopt:`state=absent`:
 
 .. code-block:: yaml+jinja
 
@@ -223,7 +223,7 @@ To delete values, you can either overwrite the values with value ``[]``, or use
         value:
           - '::1'
 
-In the third example, ``on_existing=keep_and_fail`` is present and an explicit value and TTL are given. This makes the module remove the current value only if there's a AAAA record for ``www.example.com`` whose current value is ``::1`` and whose TTL is 300. If another value is set, the module will not make any change, but fail. This can be useful to not accidentally remove values you do not want to change. To issue a warning instead of failing, use ``on_existing=keep_and_warn``, and to simply not do a change without any indication of this situation, use ``on_existing=keep``.
+In the third example, :ansopt:`on_existing=keep_and_fail` is present and an explicit value and TTL are given. This makes the module remove the current value only if there's a AAAA record for ``www.example.com`` whose current value is ``::1`` and whose TTL is 300. If another value is set, the module will not make any change, but fail. This can be useful to not accidentally remove values you do not want to change. To issue a warning instead of failing, use :ansopt:`on_existing=keep_and_warn`, and to simply not do a change without any indication of this situation, use :ansopt:`on_existing=keep`.
 
 Bulk synchronization of DNS record sets
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -248,7 +248,7 @@ The following example shows up to set/update multiple records at once:
             value:
               - '::1'
 
-The next example shows how to make sure that only the given records are available and all other records are deleted. Note that for the ``type=NS`` record we used ``ignore=true``, which allows us to skip the value. It tells the module that it should not touch the ``NS`` record for ``example.com``.
+The next example shows how to make sure that only the given records are available and all other records are deleted. Note that for the :ansopt:`type=NS` record we used :ansopt:`ignore=true`, which allows us to skip the value. It tells the module that it should not touch the ``NS`` record for ``example.com``.
 
 .. code-block:: yaml+jinja
 
@@ -290,7 +290,7 @@ The markuman.hetzner_dns.record module
 
 The ``markuman.hetzner_dns.zone_info`` module can be replaced by the :ref:`community.dns.hetzner_dns_record module <ansible_collections.community.dns.hetzner_dns_record_module>` and the :ref:`community.dns.hetzner_dns_record_set module <ansible_collections.community.dns.hetzner_dns_record_set_module>`, depending on what it is used for.
 
-When creating, updating or removing single records, the :ref:`community.dns.hetzner_dns_record module <ansible_collections.community.dns.hetzner_dns_record_module>` should be used. This is the case when ``purge=false`` is specified (the default value). Note that ``replace``, ``overwrite`` and ``solo`` are aliases of ``purge``.
+When creating, updating or removing single records, the :ref:`community.dns.hetzner_dns_record module <ansible_collections.community.dns.hetzner_dns_record_module>` should be used. This is the case when :ansopt:`purge=false` is specified (the default value). Note that :ansopt:`replace`, :ansopt:`overwrite` and :ansopt:`solo` are aliases of :ansopt:`purge`.
 
 .. code-block:: yaml+jinja
 
@@ -356,7 +356,7 @@ When the ``markuman.hetzner_dns.record`` module is in replace mode, it should be
         #
         #     value: 127.0.0.1
 
-When deleting a record, it depends on whether ``value`` is specified or not. If ``value`` is specified, the module is deleting a single DNS record, and the :ref:`community.dns.hetzner_dns_record module <ansible_collections.community.dns.hetzner_dns_record_module>` should be used:
+When deleting a record, it depends on whether :ansopt:`value` is specified or not. If :ansopt:`value` is specified, the module is deleting a single DNS record, and the :ref:`community.dns.hetzner_dns_record module <ansible_collections.community.dns.hetzner_dns_record_module>` should be used:
 
 .. code-block:: yaml+jinja
 
@@ -383,7 +383,7 @@ When deleting a record, it depends on whether ``value`` is specified or not. If
         value: 127.0.0.1
         ttl: 60
 
-When ``value`` is not specified, the ``markuman.hetzner_dns.record`` module will delete all records for this prefix and type. In that case, it operates on a record set and the :ref:`community.dns.hetzner_dns_record_set module <ansible_collections.community.dns.hetzner_dns_record_set_module>` should be used:
+When :ansopt:`value` is not specified, the ``markuman.hetzner_dns.record`` module will delete all records for this prefix and type. In that case, it operates on a record set and the :ref:`community.dns.hetzner_dns_record_set module <ansible_collections.community.dns.hetzner_dns_record_set_module>` should be used:
 
 .. code-block:: yaml+jinja
 
@@ -406,22 +406,22 @@ When ``value`` is not specified, the ``markuman.hetzner_dns.record`` module will
         # 'type' does not change:
         type: A
 
-A last step is replacing the deprecated alias ``name`` of ``prefix`` by ``prefix``. This can be done later though, if you do not mind the deprecation warnings.
+A last step is replacing the deprecated alias :ansopt:`name` of :ansopt:`prefix` by :ansopt:`prefix`. This can be done later though, if you do not mind the deprecation warnings.
 
 The markuman.hetzner_dns.record_info module
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The ``markuman.hetzner_dns.record_info`` module can be replaced by the :ref:`community.dns.hetzner_dns_record_set_info module <ansible_collections.community.dns.hetzner_dns_record_set_info_module>`. There are two big differences:
 
-1. Instead of with the ``filters`` option, the output is controlled by the ``what`` option (choices ``single_record``, ``all_types_for_record``, and ``all_records``), the ``type`` option (needed when ``what=single_record``), and the ``record`` and ``prefix`` options (needed when ``what`` is not ``all_records``).
-2. The module returns **record sets** instead of individual records. This means that for example all A record for the prefix ``*`` are returned as one entry (with multiple values), instead of a list of records (which each a single value).
+1. Instead of with the :ansopt:`filters` option, the output is controlled by the :ansopt:`what` option (choices :ansval:`single_record`, :ansval:`all_types_for_record`, and :ansval:`all_records`), the :ansopt:`type` option (needed when :ansopt:`what=single_record`), and the :ansopt:`record` and :ansopt:`prefix` options (needed when :ansopt:`what` is not :ansval:`all_records`).
+2. The module returns **record sets** instead of individual records. This means that for example all A record for the prefix :ansval:`*` are returned as one entry (with multiple values), instead of a list of records (which each a single value).
 
 The markuman.hetzner_dns.zone_info module
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The ``markuman.hetzner_dns.zone_info`` module can be replaced by the :ref:`community.dns.hetzner_dns_zone_info module <ansible_collections.community.dns.hetzner_dns_zone_info_module>`. The main differences are:
 
-1. The parameter ``name`` must be changed to ``zone_name`` or ``zone``.
+1. The parameter :ansopt:`name` must be changed to :ansopt:`zone_name` or :ansopt:`zone`.
 2. The return value ``zone_info`` no longer has the ``name`` and ``id`` entries. Use the return values ``zone_name`` and ``zone_id`` instead.
 
 The markuman.hetzner_dns.inventory inventory plugin

docs/docsite/rst/hosttech_guide.rst

@@ -30,7 +30,7 @@ HostTech currently has two APIs for working with DNS records: the old WSDL-based
 JSON REST API
 ~~~~~~~~~~~~~
 
-To use the JSON REST API, you need to create a API token. You can manage API tokens in the "DNS Editor" in the "API" section. You must provide the token to the ``hosttech_token`` option of the modules:
+To use the JSON REST API, you need to create a API token. You can manage API tokens in the "DNS Editor" in the "API" section. You must provide the token to the :ansopt:`hosttech_token` option of the modules:
 
 .. code-block:: yaml+jinja
 
@@ -43,7 +43,7 @@ In the examples in this guide, we will leave the authentication options away. Pl
 WSDL API
 ~~~~~~~~
 
-To use the WSDL API, you need to set API credentials. These can be found and changed in the "Servercenter" and there in the "Solutions" section under settings for the "DNS Tool". The username is fixed, but the password can be changed. The credentials must be provided to the ``hosttech_username`` and ``hosttech_password`` options of the modules.
+To use the WSDL API, you need to set API credentials. These can be found and changed in the "Servercenter" and there in the "Solutions" section under settings for the "DNS Tool". The username is fixed, but the password can be changed. The credentials must be provided to the :ansopt:`hosttech_username` and :ansopt:`hosttech_password` options of the modules.
 
 You also need to install the `lxml Python module <https://pypi.org/project/lxml/>`_ to work with the WSDL API. This can be done before using the modules:
 
@@ -119,7 +119,7 @@ The :ref:`community.dns.hosttech_dns_record_set_info module <ansible_collections
         msg: There is no A record for www.example.com
       when: not result.set
 
-In all examples in this section, you can replace ``zone_name: example.com`` by ``zone_id: 42`` with the zone's integer ID.
+In all examples in this section, you can replace :ansopt:`zone_name=example.com` by :ansopt:`zone_id=42` with the zone's integer ID.
 
 You can also query a list of all records for a record name or prefix:
 
@@ -180,7 +180,7 @@ The :ref:`community.dns.hosttech_dns_record module <ansible_collections.communit
         value: 1.1.1.1
         ttl: 300
 
-To delete records, simply use ``state: absent``. Records will be matched by record name and type, and the TTL will be ignored:
+To delete records, simply use :ansopt:`state=absent`. Records will be matched by record name and type, and the TTL will be ignored:
 
 .. code-block:: yaml+jinja
 
@@ -214,9 +214,9 @@ The :ref:`community.dns.hosttech_dns_record_set module <ansible_collections.comm
           - 1.1.1.1
           - 8.8.8.8
 
-If you want to assert that a record has a certain value, set ``on_existing: keep``. Using ``keep_and_warn`` instead will emit a warning if this happens, and ``keep_and_fail`` will make the module fail.
+If you want to assert that a record has a certain value, set :ansopt:`on_existing=keep`. Using :ansval:`keep_and_warn` instead will emit a warning if this happens, and :ansval:`keep_and_fail` will make the module fail.
 
-To delete values, you can either overwrite the values with value ``[]``, or use ``state: absent``:
+To delete values, you can either overwrite the values with value :ansval:`[]`, or use :ansopt:`state=absent`:
 
 .. code-block:: yaml+jinja
 
@@ -246,7 +246,7 @@ To delete values, you can either overwrite the values with value ``[]``, or use
         value:
           - '::1'
 
-In the third example, ``on_existing: keep_and_fail`` is present and an explicit value and TTL are given. This makes the module remove the current value only if there's a AAAA record for ``www.example.com`` whose current value is ``::1`` and whose TTL is 300. If another value is set, the module will not make any change, but fail. This can be useful to not accidentally remove values you do not want to change. To issue a warning instead of failing, use ``on_existing: keep_and_warn``, and to simply not do a change without any indication of this situation, use ``on_existing: keep``.
+In the third example, :ansopt:`on_existing=keep_and_fail` is present and an explicit value and TTL are given. This makes the module remove the current value only if there's a AAAA record for ``www.example.com`` whose current value is ``::1`` and whose TTL is 300. If another value is set, the module will not make any change, but fail. This can be useful to not accidentally remove values you do not want to change. To issue a warning instead of failing, use :ansopt:`on_existing=keep_and_warn`, and to simply not do a change without any indication of this situation, use :ansopt:`on_existing=keep`.
 
 Bulk synchronization of DNS record sets
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -271,7 +271,7 @@ The following example shows up to set/update multiple records at once:
             value:
               - '::1'
 
-The next example shows how to make sure that only the given records are available and all other records are deleted. Note that for the ``type: NS`` record we used ``ignore: true``, which allows us to skip the value. It tells the module that it should not touch the ``NS`` record for ``example.com``.
+The next example shows how to make sure that only the given records are available and all other records are deleted. Note that for the :ansopt:`type=NS` record we used :ansopt:`ignore=true`, which allows us to skip the value. It tells the module that it should not touch the ``NS`` record for ``example.com``.
 
 .. code-block:: yaml+jinja
 

plugins/doc_fragments/hetzner.py

@@ -15,7 +15,7 @@ class ModuleDocFragment(object):
     hetzner_token:
         description:
           - The token for the Hetzner API.
-          - If not provided, will be read from the environment variable C(HETZNER_DNS_TOKEN).
+          - If not provided, will be read from the environment variable E(HETZNER_DNS_TOKEN).
         aliases:
           - api_token
         type: str
@@ -76,17 +76,17 @@ class ModuleDocFragment(object):
             record:
                 description:
                   - The full DNS record to create or delete.
-                  - Exactly one of I(record) and I(prefix) must be specified.
+                  - Exactly one of O(record) and O(prefix) must be specified.
                 type: str
             prefix:
                 description:
                   - The prefix of the DNS record.
-                  - This is the part of I(record) before I(zone_name). For example,
+                  - This is the part of O(record) before O(zone_name). For example,
                       if the record to be modified is C(www.example.com) for the zone
-                      C(example.com), the prefix is C(www). If the record in this
-                      example would be C(example.com), the prefix would be C('') (empty
+                      C(example.com), the prefix is V(www). If the record in this
+                      example would be C(example.com), the prefix would be V('') (empty
                       string).
-                  - Exactly one of I(record) and I(prefix) must be specified.
+                  - Exactly one of O(record) and O(prefix) must be specified.
                 type: str
             ttl:
                 description:
@@ -119,13 +119,13 @@ class ModuleDocFragment(object):
                   - YAML lists or multiple comma-spaced values are allowed.
                   - When deleting a record all values for the record must be specified
                       or it will not be deleted.
-                  - Must be specified if I(ignore=false).
+                  - Must be specified if O(ignore=false).
                 type: list
                 elements: str
             ignore:
                 description:
-                  - If set to C(true), I(value) will be ignored.
-                  - This is useful when I(prune=true), but you do not want certain
+                  - If set to V(true), O(value) will be ignored.
+                  - This is useful when O(prune=true), but you do not want certain
                       entries to be removed without having to know their current value.
                 type: bool
                 default: false