Fix/improve version_added

changelogs/fragments/34-version_added.yml

@@ -0,0 +1,4 @@
+bugfixes:
+  - "Fix escaping of collection names in version added statements, and fix collection names for roles options (https://github.com/ansible-community/antsibull-docs/pull/34)."
+minor_changes:
+  - "Replace ``ansible.builtin`` with ``ansible-core`` in version added collection names (https://github.com/ansible-community/antsibull-docs/pull/34)."

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

@@ -4,6 +4,8 @@
   SPDX-License-Identifier: GPL-3.0-or-later
 #}
 
+{% from 'macros/version_added.rst.j2' import version_added_rst %}
+
 {% macro in_rst(attributes) %}
 .. rst-class:: ansible-option-table
 
@@ -70,9 +72,9 @@
 {%-    endif %}
 {%   endif %}
 
-{%   if data['version_added'] is still_relevant(collection=data['version_added_collection']) %}
+{%   if data['version_added'] is still_relevant(collection=data['version_added_collection'] or collection) %}
 
-      :ansible-option-versionadded:`added in @{data['version_added']}@ of @{ data['version_added_collection'] | rst_escape }@`
+      :ansible-option-versionadded:`added in @{ version_added_rst(data['version_added'], data['version_added_collection'] or collection) }@`
 {%   endif %}
 
 {%   for desc in data['details'] %}

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

@@ -6,6 +6,7 @@
 
 {% from 'macros/deprecates.rst.j2' import in_rst as deprecates_rst with context %}
 {% from 'macros/deprecates.rst.j2' import in_html as deprecates_html with context %}
+{% from 'macros/version_added.rst.j2' import version_added_rst, version_added_html %}
 
 {% macro in_rst(elements, suboption_key='suboptions', parameter_html_prefix='', parameter_rst_prefix='') %}
 .. rst-class:: ansible-option-table
@@ -50,10 +51,10 @@
       :ansible-option-type:`@{ value['type'] | documented_type }@`
       {%- if value['type'] == 'list' and value['elements'] is not none %} / :ansible-option-elements:`elements=@{ value['elements'] | documented_type }@`{% endif -%}
       {%- if value['required'] %} / :ansible-option-required:`required`{% endif %}
-{%-   if value['version_added'] is still_relevant(collection=value['version_added_collection']) %}
+{%-   if value['version_added'] is still_relevant(collection=value['version_added_collection'] or collection) %}
 
 
-      :ansible-option-versionadded:`added in @{value['version_added']}@ of @{ value['version_added_collection'] | escape }@`
+      :ansible-option-versionadded:`added in @{ version_added_rst(value['version_added'], value['version_added_collection'] or collection) }@`
 {%   endif %}
 {%-   if plugin_type != 'module' %}
 
@@ -129,41 +130,41 @@
           [@{ ini['section'] }@]
           @{ ini['key'] }@ = @{ value['default'] | default('VALUE') }@
 
-{%         if ini['version_added'] is still_relevant(collection=ini['version_added_collection']) %}
-        :ansible-option-versionadded:`added in @{ini['version_added']}@ of @{ ini['version_added_collection'] | rst_ify }@`
+{%         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) }@`
 {%         endif %}
 @{         deprecates_rst(ini['deprecated'], collection, 8) }@
 {%       endfor %}
 {%     endif %}
 {%     for env in value['env'] %}
       - Environment variable: @{ env['name'] | rst_escape }@
-{%       if env['version_added'] is still_relevant(collection=env['version_added_collection']) %}
+{%       if env['version_added'] is still_relevant(collection=env['version_added_collection'] or collection) %}
 
-        :ansible-option-versionadded:`added in @{env['version_added']}@ of @{ env['version_added_collection'] | rst_ify }@`
+        :ansible-option-versionadded:`added in @{ version_added_rst(env['version_added'], env['version_added_collection'] or collection) }@`
 {%       endif %}
 @{       deprecates_rst(env['deprecated'], collection, 8) }@
 {%     endfor %}
 {%     for myvar in value['vars'] %}
       - Variable: @{ myvar['name'] | rst_escape }@
-{%       if myvar['version_added'] is still_relevant(collection=myvar['version_added_collection']) %}
+{%       if myvar['version_added'] is still_relevant(collection=myvar['version_added_collection'] or collection) %}
 
-        :ansible-option-versionadded:`added in @{myvar['version_added']}@ of @{ myvar['version_added_collection'] | rst_ify }@`
+        :ansible-option-versionadded:`added in @{ version_added_rst(myvar['version_added'], myvar['version_added_collection'] or collection) }@`
 {%       endif %}
 @{       deprecates_rst(myvar['deprecated'], collection, 8) }@
 {%     endfor %}
 {%     for kw in value['keyword'] %}
       - Keyword: @{ kw['name'] | rst_escape }@
-{%       if kw['version_added'] is still_relevant(collection=kw['version_added_collection']) %}
+{%       if kw['version_added'] is still_relevant(collection=kw['version_added_collection'] or collection) %}
 
-        :ansible-option-versionadded:`added in @{kw['version_added']}@ of @{ kw['version_added_collection'] | rst_ify }@`
+        :ansible-option-versionadded:`added in @{ version_added_rst(kw['version_added'], kw['version_added_collection'] or collection) }@`
 {%       endif %}
 @{       deprecates_rst(kw['deprecated'], collection, 8) }@
 {%     endfor %}
 {%     for mycli in value['cli'] %}
       - CLI argument: @{ mycli['option'] | rst_escape }@
-{%       if mycli['version_added'] is still_relevant(collection=mycli['version_added_collection']) %}
+{%       if mycli['version_added'] is still_relevant(collection=mycli['version_added_collection'] or collection) %}
 
-        :ansible-option-versionadded:`added in @{mycli['version_added']}@ of @{ mycli['version_added_collection'] | rst_ify }@`
+        :ansible-option-versionadded:`added in @{ version_added_rst(mycli['version_added'], mycli['version_added_collection'] or collection) }@`
 {%       endif %}
 @{       deprecates_rst(mycli['deprecated'], collection, 8) }@
 {%     endfor %}
@@ -213,8 +214,8 @@
         / <span class="ansible-option-required">required</span>
 {%   endif %}
       </p>
-{%   if value['version_added'] is still_relevant(collection=value['version_added_collection']) %}
-      <p><span class="ansible-option-versionadded">added in @{value['version_added']}@ of @{ value['version_added_collection'] | escape }@</span></p>
+{%   if value['version_added'] is still_relevant(collection=value['version_added_collection'] or collection) %}
+      <p><span class="ansible-option-versionadded">added in @{ version_added_html(value['version_added'], value['version_added_collection'] or collection) }@</span></p>
 {%   endif %}
 {%   if plugin_type != 'module' %}
 @{     deprecates_html(value['deprecated'], collection) }@
@@ -268,8 +269,8 @@
 {%       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 ini['version_added'] is still_relevant(collection=ini['version_added_collection']) %}
-        <p><span class="ansible-option-versionadded">added in @{ini['version_added']}@ of @{ ini['version_added_collection'] | html_ify }@</span></p>
+{%         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 %}
 @{         deprecates_html(ini['deprecated'], collection) }@
 {%       endfor %}
@@ -278,35 +279,35 @@
 {%     for env in value['env'] %}
       <li>
         <p>Environment variable: @{ env['name'] | escape }@</p>
-{%       if env['version_added'] is still_relevant(collection=env['version_added_collection']) %}
-        <p><span class="ansible-option-versionadded">added in @{env['version_added']}@ of @{ env['version_added_collection'] | html_ify }@</span></p>
+{%       if env['version_added'] is still_relevant(collection=env['version_added_collection'] or collection) %}
+        <p><span class="ansible-option-versionadded">added in @{ version_added_html(env['version_added'], env['version_added_collection'] or collection) }@</span></p>
 {%       endif %}
 @{       deprecates_html(env['deprecated'], collection) }@
       </li>
 {%     endfor %}
 {%     for myvar in value['vars'] %}
       <li>
         <p>Variable: @{ myvar['name'] | escape }@</p>
-{%       if myvar['version_added'] is still_relevant(collection=myvar['version_added_collection']) %}
-        <p><span class="ansible-option-versionadded">added in @{myvar['version_added']}@ of @{ myvar['version_added_collection'] | html_ify }@</span></p>
+{%       if myvar['version_added'] is still_relevant(collection=myvar['version_added_collection'] or collection) %}
+        <p><span class="ansible-option-versionadded">added in @{ version_added_html(myvar['version_added'], myvar['version_added_collection'] or collection) }@</span></p>
 {%       endif %}
 @{       deprecates_html(myvar['deprecated'], collection) }@
       </li>
 {%     endfor %}
 {%     for kw in value['keyword'] %}
       <li>
         <p>Keyword: @{ kw['name'] | escape }@</p>
-{%       if kw['version_added'] is still_relevant(collection=kw['version_added_collection']) %}
-        <p><span class="ansible-option-versionadded">added in @{kw['version_added']}@ of @{ kw['version_added_collection'] | html_ify }@</span></p>
+{%       if kw['version_added'] is still_relevant(collection=kw['version_added_collection'] or collection) %}
+        <p><span class="ansible-option-versionadded">added in @{ version_added_html(kw['version_added'], kw['version_added_collection'] or collection) }@</span></p>
 {%       endif %}
 @{       deprecates_html(kw['deprecated'], collection) }@
       </li>
 {%     endfor %}
 {%     for mycli in value['cli'] %}
       <li>
         <p>CLI argument: @{ mycli['option'] | escape }@</p>
-{%       if mycli['version_added'] is still_relevant(collection=mycli['version_added_collection']) %}
-        <p><span class="ansible-option-versionadded">added in @{mycli['version_added']}@ of @{ mycli['version_added_collection'] | html_ify }@</span></p>
+{%       if mycli['version_added'] is still_relevant(collection=mycli['version_added_collection'] or collection) %}
+        <p><span class="ansible-option-versionadded">added in @{ version_added_html(mycli['version_added'], mycli['version_added_collection'] or collection) }@</span></p>
 {%       endif %}
 @{       deprecates_html(mycli['deprecated'], collection) }@
       </li>

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

@@ -4,6 +4,8 @@
   SPDX-License-Identifier: GPL-3.0-or-later
 #}
 
+{% from 'macros/version_added.rst.j2' import version_added_rst, version_added_html %}
+
 {% macro in_rst(elements) %}
 .. rst-class:: ansible-option-table
 
@@ -40,10 +42,10 @@
 
       :ansible-option-type:`@{ value['type'] | documented_type }@`
       {%- if value['type'] == 'list' and value['elements'] is not none %} / :ansible-option-elements:`elements=@{ value['elements'] | documented_type }@`{% endif %}
-{%-   if value['version_added'] is still_relevant(collection=value['version_added_collection']) %}
+{%-   if value['version_added'] is still_relevant(collection=value['version_added_collection'] or collection) %}
 
 
-      :ansible-option-versionadded:`added in @{value['version_added']}@ of @{ value['version_added_collection'] | rst_escape }@`
+      :ansible-option-versionadded:`added in @{ version_added_rst(value['version_added'], value['version_added_collection'] or collection) }@`
 {%   endif %}
 {#   description #}
 
@@ -135,8 +137,8 @@
         / <span class="ansible-option-elements">elements=@{ value['elements'] | documented_type }@</span>
 {%   endif %}
       </p>
-{%   if value['version_added'] is still_relevant(collection=value['version_added_collection']) %}
-      <p><span class="ansible-option-versionadded">added in @{value['version_added']}@ of @{ value['version_added_collection'] | escape }@</span></p>
+{%   if value['version_added'] is still_relevant(collection=value['version_added_collection'] or collection) %}
+      <p><span class="ansible-option-versionadded">added in @{ version_added_html(value['version_added'], value['version_added_collection'] or collection) }@</span></p>
 {%   endif %}
     </div></td>
 {#   description #}

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

@@ -0,0 +1,23 @@
+{#
+  Copyright (c) Ansible Project
+  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
+#}
+
+{% macro version_added_rst(version_added, version_added_collection) -%}
+@{ version_added | rst_escape }@
+{%-   if version_added_collection == 'ansible.builtin' %}
+ of ansible-core
+{%-   elif version_added_collection %}
+ of @{ version_added_collection | rst_escape }@
+{%-   endif -%}
+{%- endmacro %}
+
+{% macro version_added_html(version_added, version_added_collection) -%}
+@{ version_added | escape }@
+{%-   if version_added_collection == 'ansible.builtin' %}
+ of ansible-core
+{%-   elif version_added_collection %}
+ of @{ version_added_collection | escape }@
+{%-   endif -%}
+{%- endmacro %}

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

@@ -9,6 +9,7 @@
 {% from 'macros/parameters.rst.j2' import in_html as parameters_html with context %}
 {% from 'macros/returnvalues.rst.j2' import in_rst as return_docs_rst with context %}
 {% from 'macros/returnvalues.rst.j2' import in_html as return_docs_html with context %}
+{% from 'macros/version_added.rst.j2' import version_added_rst %}
 .. Document meta
 
 :orphan:
@@ -110,8 +111,8 @@
 
 .. version_added
 
-{% if doc['version_added'] is still_relevant(collection=doc['version_added_collection']) -%}
-.. versionadded:: @{ doc['version_added'] }@ of @{ doc['version_added_collection'] | rst_ify }@
+{% if doc['version_added'] is still_relevant(collection=doc['version_added_collection'] or collection) -%}
+.. versionadded:: @{ version_added_rst(doc['version_added'], doc['version_added_collection'] or collection) }@
 {% endif %}
 
 .. contents::

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

@@ -6,6 +6,7 @@
 
 {% from 'macros/parameters.rst.j2' import in_rst as parameters_rst with context %}
 {% from 'macros/parameters.rst.j2' import in_html as parameters_html with context %}
+{% from 'macros/version_added.rst.j2' import version_added_rst %}
 .. Document meta
 
 :orphan:
@@ -91,7 +92,7 @@
 .. version_added
 
 {%   if ep_doc['version_added'] is still_relevant(collection=collection) -%}
-.. versionadded:: @{ ep_doc['version_added'] }@ of @{ collection | rst_ify }@
+.. versionadded:: @{ version_added_rst(ep_doc['version_added'], collection) }@
 {%   endif %}
 
 .. Deprecated