Remove superfluous whitespace or escaped spaces from templates (#313)

* Remove superfluous whitespace or escaped spaces from templates.

* Remove trialing whitespaces from author cleanup tests.

changelogs/fragments/313-whitespace.yml

@@ -0,0 +1,2 @@
+minor_changes:
+  - "Remove superfluous whitespace or escaped spaces from templates (https://github.com/ansible-community/antsibull-docs/pull/313)."

src/antsibull_docs/data/docsite/ansible-docsite/plugin.rst.j2

@@ -327,13 +327,13 @@ See Also
 
 .. Examples
 
-{% if examples -%}
+{% if examples and examples | trim -%}
 Examples
 --------
 
 .. code-block:: @{ examples_format | rst_format(for_sphinx=true) }@
 
-@{ examples | indent(4, True) }@
+@{ examples | sanitize_whitespace | indent(4, True) }@
 
 {% endif %}
 

src/antsibull_docs/data/docsite/ansible-docsite/role.rst.j2

@@ -189,13 +189,13 @@ See Also
 {%     endfor %}
 {%   endif %}
 
-{%   if ep_doc['examples'] -%}
+{%   if ep_doc['examples'] and ep_doc['examples'] | trim -%}
 Examples
 --------
 
 .. code-block:: @{ ep_doc['examples_format'] | rst_format(for_sphinx=true) }@
 
-@{     ep_doc['examples'] | indent(4, True) }@
+@{     ep_doc['examples'] | sanitize_whitespace | indent(4, True) }@
 
 {%   endif %}
 

src/antsibull_docs/data/docsite/simplified-rst/macros/attributes.rst.j2

@@ -49,7 +49,7 @@
 {%   endfor %}
 
 {#   description #}
-    - 
+    -
 {% for desc in data['description'] %}
       @{ desc | rst_ify(role_entrypoint=role_entrypoint) | rst_indent(6) }@
 

src/antsibull_docs/data/docsite/simplified-rst/plugin.rst.j2

@@ -256,13 +256,13 @@ See Also
 {% endfor %}
 {% endif %}
 
-{% if examples -%}
+{% if examples and examples | trim -%}
 Examples
 --------
 
 .. code-block:: @{ examples_format | rst_format }@
 
-@{ examples | indent(4, True) }@
+@{ examples | sanitize_whitespace | indent(4, True) }@
 
 {% endif %}
 

src/antsibull_docs/data/docsite/simplified-rst/role.rst.j2

@@ -146,13 +146,13 @@ See Also
 {%     endfor %}
 {%   endif %}
 
-{%   if ep_doc['examples'] -%}
+{%   if ep_doc['examples'] and ep_doc['examples'] | trim -%}
 Examples
 --------
 
 .. code-block:: @{ ep_doc['examples_format'] | rst_format }@
 
-@{     ep_doc['examples'] | indent(4, True) }@
+@{     ep_doc['examples'] | sanitize_whitespace | indent(4, True) }@
 
 {%   endif %}
 

src/antsibull_docs/jinja2/environment.py

@@ -37,6 +37,7 @@
     rst_format,
     rst_indent,
     rst_xline,
+    sanitize_whitespace,
     suboption_depth,
     to_ini_value,
     to_json,
@@ -46,14 +47,14 @@
 
 def reference_plugin_rst(plugin_name: str, plugin_type: str) -> str:
     fqcn = f"{plugin_name}"
-    return f"\\ :ref:`{rst_escape(fqcn)} <{get_plugin_ref(fqcn, plugin_type)}>`\\ "
+    return f":ref:`{rst_escape(fqcn)} <{get_plugin_ref(fqcn, plugin_type)}>`"
 
 
 def reference_plugin_rst_simplified(plugin_name: str, plugin_type: str) -> str:
     fqcn = f"{plugin_name}"
-    # TODO: return f"\\ {fqcn}\\ " for other collections
+    # TODO: return fqcn for other collections
     name = plugin_name.split(".", 2)[2]
-    return f"\\ `{rst_escape(fqcn)} <{name}_{plugin_type}.rst>`__\\ "
+    return f"`{rst_escape(fqcn)} <{name}_{plugin_type}.rst>`__"
 
 
 def make_reference_plugin_rst(output_format: OutputFormat):
@@ -171,6 +172,7 @@ def doc_environment(
     env.filters["suboption_depth"] = suboption_depth
     env.filters["rst_format"] = rst_format
     env.filters["rst_indent"] = rst_indent
+    env.filters["sanitize_whitespace"] = sanitize_whitespace
     if collection_url is not None:
         env.filters["collection_url"] = collection_url
     if collection_install is not None:

src/antsibull_docs/jinja2/filters.py

@@ -21,6 +21,7 @@
 from ..markup.htmlify import html_ify as html_ify_impl
 from ..markup.rstify import get_rst_formatter_link_provider
 from ..markup.rstify import rst_ify as rst_ify_impl
+from ..utils.text import sanitize_whitespace as _sanitize_whitespace
 from . import OutputFormat
 
 mlog = log.fields(mod=__name__)
@@ -98,7 +99,7 @@ def massage_author_name(value):
     """remove email addresses from the given string, and remove `(!UNKNOWN)`"""
     value = _EMAIL_ADDRESS.sub("", value)
     value = value.replace("(!UNKNOWN)", "")
-    return value
+    return value.strip()
 
 
 def extract_options_from_list(
@@ -288,3 +289,9 @@ def rst_indent(
             )
 
     return indent + rv if first else rv
+
+
+def sanitize_whitespace(text: str) -> str:
+    if not isinstance(text, str):
+        raise ValueError("sanitize_whitespace can only be applied to strings")
+    return _sanitize_whitespace(text)

src/antsibull_docs/utils/text.py

@@ -0,0 +1,59 @@
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or
+# https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+# SPDX-FileCopyrightText: 2024, Ansible Project
+"""
+Text utils.
+"""
+
+import typing as t
+
+
+def count_leading_whitespace(
+    line: str, *, max_count: t.Optional[int] = None
+) -> t.Optional[int]:
+    """
+    Count the number of leading whitespace for the given line.
+
+    If ``max_count`` is given, will not return numbers greater than ``max_count``.
+    If the line completely consists out of whitespace, ``None`` is returned.
+    """
+    length = len(line)
+    to_check = length
+    if max_count is not None and max_count < to_check:
+        to_check = max_count
+    count = 0
+    while count < to_check and line[count] in " \t":
+        count += 1
+    if count == length:
+        return None
+    return count
+
+
+def sanitize_whitespace(content: str) -> str:
+    # Split into lines and remove trailing whitespace
+    lines = [line.rstrip(" \t") for line in content.splitlines()]
+
+    # Remove starting and trailing empty lines
+    start = 0
+    end = len(lines)
+    while start < end and lines[start] == "":
+        start += 1
+    while start < end and lines[end - 1] == "":
+        end -= 1
+    lines = lines[start:end]
+
+    # Remove common leading whitespace
+    common_whitespace = None
+    for line in lines:
+        whitespace = count_leading_whitespace(line, max_count=common_whitespace)
+        if whitespace is not None:
+            if common_whitespace is None or common_whitespace > whitespace:
+                common_whitespace = whitespace
+                if common_whitespace == 0:
+                    break
+    if common_whitespace is not None and common_whitespace > 0:
+        lines = [line[common_whitespace:] for line in lines]
+
+    # Re-combine the result
+    return "\n".join(lines)

tests/functional/baseline-default/collections/ns/col2/bar_role.rst

@@ -115,11 +115,11 @@ See Also
 
 .. seealso::
 
-   \ :ref:`ns2.col.foo <ansible_collections.ns2.col.foo_module>`\ 
+   :ref:`ns2.col.foo <ansible_collections.ns2.col.foo_module>`
        The official documentation on the **ns2.col.foo** module.
-   \ :ref:`ns2.col.foobarbaz <ansible_collections.ns2.col.foobarbaz_module>`\ 
+   :ref:`ns2.col.foobarbaz <ansible_collections.ns2.col.foobarbaz_module>`
        The official documentation on the **ns2.col.foobarbaz** module.
-   \ :ref:`ns2.col.foo <ansible_collections.ns2.col.foo_lookup>`\  lookup plugin
+   :ref:`ns2.col.foo <ansible_collections.ns2.col.foo_lookup>` lookup plugin
        The official documentation on the **ns2.col.foo** lookup plugin.
 
 

tests/functional/baseline-default/collections/ns/col2/foo2_module.rst

@@ -474,21 +474,21 @@ See Also
 
 .. seealso::
 
-   \ :ref:`ns.col2.foo3 <ansible_collections.ns.col2.foo3_module>`\ 
+   :ref:`ns.col2.foo3 <ansible_collections.ns.col2.foo3_module>`
        Foo III.
-   \ :ref:`ns.col2.foobarbaz <ansible_collections.ns.col2.foobarbaz_module>`\ 
+   :ref:`ns.col2.foobarbaz <ansible_collections.ns.col2.foobarbaz_module>`
        The official documentation on the **ns.col2.foobarbaz** module.
-   \ :ref:`ns.col2.foo4 <ansible_collections.ns.col2.foo4_module>`\  module plugin
+   :ref:`ns.col2.foo4 <ansible_collections.ns.col2.foo4_module>` module plugin
        Markup reference linting test.
-   \ :ref:`ns.col2.foobarbaz <ansible_collections.ns.col2.foobarbaz_inventory>`\  inventory plugin
+   :ref:`ns.col2.foobarbaz <ansible_collections.ns.col2.foobarbaz_inventory>` inventory plugin
        The official documentation on the **ns.col2.foobarbaz** inventory plugin.
-   \ :ref:`ansible.builtin.service <ansible_collections.ansible.builtin.service_module>`\ 
+   :ref:`ansible.builtin.service <ansible_collections.ansible.builtin.service_module>`
        The service module.
-   \ :ref:`ansible.builtin.foobarbaz <ansible_collections.ansible.builtin.foobarbaz_module>`\ 
+   :ref:`ansible.builtin.foobarbaz <ansible_collections.ansible.builtin.foobarbaz_module>`
        A non-existing module.
-   \ :ref:`ansible.builtin.linear <ansible_collections.ansible.builtin.linear_strategy>`\  strategy plugin
+   :ref:`ansible.builtin.linear <ansible_collections.ansible.builtin.linear_strategy>` strategy plugin
        The linear strategy plugin.
-   \ :ref:`ansible.builtin.foobarbaz <ansible_collections.ansible.builtin.foobarbaz_strategy>`\  strategy plugin
+   :ref:`ansible.builtin.foobarbaz <ansible_collections.ansible.builtin.foobarbaz_strategy>` strategy plugin
        Foo bar baz. Bamm - Bar baz
        bam bum.
        Bumm - Foo bar
@@ -501,12 +501,10 @@ Examples
 
 .. code-block:: yaml+jinja
 
-
     name: This is YAML.
 
 
 
-
 .. Facts
 
 

tests/functional/baseline-default/collections/ns/col2/foo3_module.rst

@@ -394,12 +394,10 @@ Examples
 
 .. code-block:: yaml+jinja
 
-
     This is not YAML.
 
 
 
-
 .. Facts
 
 

tests/functional/baseline-default/collections/ns2/col/bar_filter.rst

@@ -323,12 +323,10 @@ Examples
 
 .. code-block:: yaml+jinja
 
-
     {'a': 1} | ns2.col.bar({'b': 2}, baz='cde')
 
 
 
-
 .. Facts
 
 

tests/functional/baseline-default/collections/ns2/col/bar_test.rst

@@ -142,7 +142,6 @@ Examples
 
 
 
-
 .. Facts
 
 

tests/functional/baseline-default/collections/ns2/col/foo2_module.rst

@@ -316,14 +316,12 @@ Examples
 
 .. code-block:: yaml+jinja
 
-
     - name: Do some foo
       ns2.col.foo2:
         bar: foo
 
 
 
-
 .. Facts
 
 

tests/functional/baseline-default/collections/ns2/col/foo_become.rst

@@ -352,7 +352,7 @@ Status
 Authors
 ~~~~~~~
 
-- Nobody 
+- Nobody
 
 
 .. hint::

tests/functional/baseline-default/collections/ns2/col/foo_cliconf.rst

@@ -91,7 +91,7 @@ Synopsis
 Authors
 ~~~~~~~
 
-- Felix Fontein (@felixfontein) 
+- Felix Fontein (@felixfontein)
 
 
 .. hint::

tests/functional/baseline-default/collections/ns2/col/foo_filter.rst

@@ -231,12 +231,10 @@ Examples
 
 .. code-block:: yaml+jinja
 
-
     some_var: "{{ 'foo' | ns2.col.foo }}"
 
 
 
-
 .. Facts
 
 

tests/functional/baseline-default/collections/ns2/col/foo_inventory.rst

@@ -134,13 +134,11 @@ Examples
 
 .. code-block:: yaml+jinja
 
-
     foo:
         bar!
 
 
 
-
 .. Facts
 
 

tests/functional/baseline-default/collections/ns2/col/foo_lookup.rst

@@ -199,14 +199,12 @@ Examples
 
 .. code-block:: yaml+jinja
 
-
     - name: Look up bar
       ansible.builtin.debug:
         msg: "{{ lookup('ns2.col.foo', 'bar') }}"
 
 
 
-
 .. Facts
 
 

tests/functional/baseline-default/collections/ns2/col/foo_module.rst

@@ -548,13 +548,13 @@ See Also
 
 .. seealso::
 
-   \ :ref:`ns2.col.foo2 <ansible_collections.ns2.col.foo2_module>`\ 
+   :ref:`ns2.col.foo2 <ansible_collections.ns2.col.foo2_module>`
        Another foo.
-   \ :ref:`ns2.col.foo <ansible_collections.ns2.col.foo_lookup>`\  lookup plugin
+   :ref:`ns2.col.foo <ansible_collections.ns2.col.foo_lookup>` lookup plugin
        Look up some foo :ansopt:`ns2.col.foo#module:bar`.
-   \ :ref:`ansible.builtin.service <ansible_collections.ansible.builtin.service_module>`\ 
+   :ref:`ansible.builtin.service <ansible_collections.ansible.builtin.service_module>`
        The service module.
-   \ :ref:`ansible.builtin.ssh <ansible_collections.ansible.builtin.ssh_connection>`\  connection plugin
+   :ref:`ansible.builtin.ssh <ansible_collections.ansible.builtin.ssh_connection>` connection plugin
        The ssh connection plugin.
 
 .. Examples
@@ -564,7 +564,6 @@ Examples
 
 .. code-block:: yaml+jinja
 
-
     - name: Do some foo
       ns2.col.foo:
         foo: '{{ foo }}'
@@ -577,7 +576,6 @@ Examples
 
 
 
-
 .. Facts