Use JSON / special serializer to format values. (#37)

changelogs/fragments/37-choices-ini-json.yml

@@ -0,0 +1,6 @@
+minor_changes:
+  - "Use JSON serializer to format choices (https://github.com/ansible-community/antsibull-docs/pull/37)."
+  - "Use special serializer to format INI values in examples (https://github.com/ansible-community/antsibull-docs/pull/37)."
+bugfixes:
+  - "For INI examples which have no default, write ``VALUE`` as intended instead of ``None`` (https://github.com/ansible-community/antsibull-docs/pull/37)."
+  - "Format lists correctly for INI examples (https://github.com/ansible-community/antsibull-docs/pull/37)."

src/antsibull_docs/data/docsite/macros/choiceslist.rst.j2

@@ -7,16 +7,10 @@
 {% macro in_rst(choices, default_value=None, has_no_default=False) %}
 {%   if choices is mapping %}
 {%     for choice, desc in choices | dictsort %}
-{#       Turn boolean values in 'true' and 'false' values #}
-{%       if choice is sameas true %}
-{%         set choice = 'true' %}
-{%       elif choice is sameas false %}
-{%         set choice = 'false' %}
-{%       endif %}
 {%       if not has_no_default and ((default_value is not list and default_value == choice) or (default_value is list and choice in default_value)) %}
-      - :ansible-option-default-bold:`@{ choice | rst_escape(escape_ending_whitespace=true) }@` :ansible-option-default:`(default)`\ :
+      - :ansible-option-default-bold:`@{ choice | antsibull_to_json | rst_escape(escape_ending_whitespace=true) }@` :ansible-option-default:`(default)`\ :
 {%       else %}
-      - :ansible-option-choices-entry:`@{ choice | rst_escape(escape_ending_whitespace=true) }@`\ :
+      - :ansible-option-choices-entry:`@{ choice | antsibull_to_json | rst_escape(escape_ending_whitespace=true) }@`\ :
 {%       endif %}
 {%       for par in desc %}
         @{ par | rst_ify | indent(8) }@
@@ -25,16 +19,10 @@
 {%     endfor %}
 {%   else %}
 {%     for choice in choices %}
-{#       Turn boolean values in 'true' and 'false' values #}
-{%       if choice is sameas true %}
-{%         set choice = 'true' %}
-{%       elif choice is sameas false %}
-{%         set choice = 'false' %}
-{%       endif %}
 {%       if not has_no_default and ((default_value is not list and default_value == choice) or (default_value is list and choice in default_value)) %}
-      - :ansible-option-default-bold:`@{ choice | rst_escape(escape_ending_whitespace=true) }@` :ansible-option-default:`← (default)`
+      - :ansible-option-default-bold:`@{ choice | antsibull_to_json | rst_escape(escape_ending_whitespace=true) }@` :ansible-option-default:`← (default)`
 {%       else %}
-      - :ansible-option-choices-entry:`@{ choice | rst_escape(escape_ending_whitespace=true) }@`
+      - :ansible-option-choices-entry:`@{ choice | antsibull_to_json | rst_escape(escape_ending_whitespace=true) }@`
 {%       endif %}
 {%     endfor %}
 {%   endif %}
@@ -45,17 +33,11 @@
       <ul class="simple">
 {%   if choices is mapping %}
 {%     for choice, desc in choices | dictsort %}
-{#       Turn boolean values in 'true' and 'false' values #}
-{%       if choice is sameas true %}
-{%         set choice = 'true' %}
-{%       elif choice is sameas false %}
-{%         set choice = 'false' %}
-{%       endif %}
         <li>
 {%       if not has_no_default and ((default_value is not list and default_value == choice) or (default_value is list and choice in default_value)) %}
-          <p><span class="ansible-option-default-bold">@{ choice | escape }@</span> <span class="ansible-option-default">(default)</span>:
+          <p><span class="ansible-option-default-bold">@{ choice | antsibull_to_json | escape }@</span> <span class="ansible-option-default">(default)</span>:
 {%       else %}
-          <p><span class="ansible-option-choices-entry">@{ choice | escape }@</span>:
+          <p><span class="ansible-option-choices-entry">@{ choice | antsibull_to_json | escape }@</span>:
 {%       endif %}
           @{ desc | first | default('') | html_ify | indent(10, blank=true) }@</p>
 {%       for line in desc[1:] %}
@@ -65,16 +47,10 @@
 {%     endfor %}
 {%   else %}
 {%     for choice in choices %}
-{#       Turn boolean values in 'true' and 'false' values #}
-{%       if choice is sameas true %}
-{%         set choice = 'true' %}
-{%       elif choice is sameas false %}
-{%         set choice = 'false' %}
-{%       endif %}
 {%       if not has_no_default and ((default_value is not list and default_value == choice) or (default_value is list and choice in default_value)) %}
-        <li><p><span class="ansible-option-default-bold">@{ choice | escape }@</span> <span class="ansible-option-default">← (default)</span></p></li>
+        <li><p><span class="ansible-option-default-bold">@{ choice | antsibull_to_json | escape }@</span> <span class="ansible-option-default">← (default)</span></p></li>
 {%       else %}
-        <li><p><span class="ansible-option-choices-entry">@{ choice | escape }@</span></p></li>
+        <li><p><span class="ansible-option-choices-entry">@{ choice | antsibull_to_json | escape }@</span></p></li>
 {%       endif %}
 {%     endfor %}
 {%   endif %}

src/antsibull_docs/data/docsite/macros/parameters.rst.j2

@@ -79,14 +79,8 @@
 
 {%   endfor %}
 {#   default / choices #}
-{#   Turn boolean values in 'true' and 'false' values #}
-{%   if value['default'] is sameas true %}
-{%     set _x = value.update({'default': 'true'}) %}
-{%   elif value['default'] is not none and value['default'] is sameas false %}
-{%     set _x = value.update({'default': 'false'}) %}
-{%   endif %}
 {%   if value['type'] == 'bool' %}
-{%     set _x = value.update({'choices': ['false', 'true']}) %}
+{%     set _x = value.update({'choices': [false, true]}) %}
 {%   endif %}
 {#   Show possible choices and highlight details #}
 {%   if value['choices'] %}
@@ -118,7 +112,11 @@
         .. code-block::
 
           [@{ ini['section'] }@]
-          @{ ini['key'] }@ = @{ value['default'] | default('VALUE') }@
+{%        if value['default'] is none %}
+          @{ ini['key'] }@ = VALUE
+{%        else %}
+          @{ ini['key'] }@ = @{ value['default'] | antsibull_to_ini_value | indent(10, blank=true) }@
+{%        endif %}
 
 {%         if ini['version_added'] is still_relevant(collection=ini['version_added_collection'] or collection) %}
         :ansible-option-versionadded:`added in @{ version_added_rst(ini['version_added'], ini['version_added_collection'] or collection) }@`
@@ -217,14 +215,8 @@
       <p>@{ desc | html_ify | indent(6, blank=true) }@</p>
 {%   endfor %}
 {#   default / choices #}
-{#   Turn boolean values in 'true' and 'false' values #}
-{%   if value['default'] is sameas true %}
-{%     set _x = value.update({'default': 'true'}) %}
-{%   elif value['default'] is not none and value['default'] is sameas false %}
-{%     set _x = value.update({'default': 'false'}) %}
-{%   endif %}
 {%   if value['type'] == 'bool' %}
-{%     set _x = value.update({'choices': ['false', 'true']}) %}
+{%     set _x = value.update({'choices': [false, true]}) %}
 {%   endif %}
 {#   Show possible choices and highlight details #}
 {%   if value['choices'] %}
@@ -244,7 +236,11 @@
         <p>INI {% if value['ini'] | length == 1 %}entry{% else %}entries{% endif %}</p>
 {%       for ini in value['ini'] %}
         <div class="highlight-YAML+Jinja notranslate"><div class="highlight"><pre><span class="p p-Indicator">[</span><span class="nv">@{ ini['section'] | escape }@</span><span class="p p-Indicator">]</span>
-  <span class="l l-Scalar l-Scalar-Plain">@{ ini['key'] | escape }@ = @{ value['default'] | default('VALUE') | escape }@</span></pre></div></div>
+{%         if value['default'] is none %}
+  <span class="l l-Scalar l-Scalar-Plain">@{ ini['key'] | escape }@ = VALUE</span></pre></div></div>
+{%         else %}
+  <span class="l l-Scalar l-Scalar-Plain">@{ ini['key'] | escape }@ = @{ value['default'] | antsibull_to_ini_value | escape }@</span></pre></div></div>
+{%         endif %}
 {%         if ini['version_added'] is still_relevant(collection=ini['version_added_collection'] or collection) %}
         <p><span class="ansible-option-versionadded">added in @{ version_added_html(ini['version_added'], ini['version_added_collection'] or collection) }@</span></p>
 {%         endif %}

src/antsibull_docs/jinja2/environment.py

@@ -14,7 +14,7 @@
 
 from .filters import (
     do_max, documented_type, rst_fmt, rst_xline, move_first, massage_author_name,
-    extract_options_from_list, remove_options_from_list, to_json,
+    extract_options_from_list, remove_options_from_list, to_json, to_ini_value,
 )
 from .htmlify import html_ify
 from .rstify import rst_ify, rst_code, rst_escape
@@ -94,6 +94,7 @@ def doc_environment(template_location: t.Union[str, t.Tuple[str, str]],
     env.filters['extract_options_from_list'] = extract_options_from_list
     env.filters['remove_options_from_list'] = remove_options_from_list
     env.filters['antsibull_to_json'] = to_json
+    env.filters['antsibull_to_ini_value'] = to_ini_value
     if collection_url is not None:
         env.filters['collection_url'] = collection_url
     if collection_install is not None:

src/antsibull_docs/jinja2/filters.py

@@ -11,6 +11,8 @@
 
 import typing as t
 
+from collections.abc import Mapping, Sequence
+
 from jinja2.runtime import Undefined
 
 from antsibull_core.logging import log
@@ -102,3 +104,16 @@ def remove_options_from_list(options: t.Dict[str, t.Any],
 
 def to_json(data: t.Any) -> str:
     return json.dumps(data, sort_keys=True, separators=(', ', ': '))
+
+
+def to_ini_value(data: t.Any) -> str:
+    if isinstance(data, (str, bytes)):
+        if not data:
+            return '""'
+        return str(data)
+    if isinstance(data, Sequence):
+        return ', '.join(to_ini_value(v) for v in data)
+    if isinstance(data, Mapping):
+        return 'MAPPINGS ARE NOT SUPPORTED'
+    # Handle other values (booleans, integers, floats) as JSON
+    return json.dumps(data)

tests/units/test_jinja2.py

@@ -4,7 +4,7 @@
 
 import pytest
 
-from antsibull_docs.jinja2.filters import move_first, massage_author_name, to_json
+from antsibull_docs.jinja2.filters import move_first, massage_author_name, to_json, to_ini_value
 from antsibull_docs.jinja2.rstify import rst_ify, rst_escape
 
 
@@ -100,3 +100,17 @@ def test_massage_author_name(input, expected):
 @pytest.mark.parametrize('input, expected', TO_JSON)
 def test_to_json(input, expected):
     assert to_json(input) == expected
+
+
+TO_INI_VALUE = [
+    ('', '""'),
+    ('<foo>', '<foo>'),
+    (1, '1'),
+    (True, 'true'),
+    (['a', 'b', 'c', 2, False], 'a, b, c, 2, false'),
+]
+
+
+@pytest.mark.parametrize('input, expected', TO_INI_VALUE)
+def test_to_ini_value(input, expected):
+    assert to_ini_value(input) == expected